@ixo/oracle-runtime-workers 0.12.0 → 0.15.0

package/src/feedback/config.ts

@@ -0,0 +1,127 @@
+/**
+ * Anonymous feedback configuration, read from the Worker env by the shell.
+ *
+ * The keys are deliberately NOT part of the validated base env
+ * (`src/core/env.ts`), so they never appear in the `ctx.config` plugins
+ * receive, and `composeEnvSchema` refuses a plugin whose `configSchema`
+ * declares a `FEEDBACK_` key. That is the whole guarantee: a plugin HTTP
+ * route (`PluginRoute.handler`) is handed the raw Worker env, which holds
+ * these keys like every other binding and secret.
+ *
+ * Off unless both the Linear key and the HMAC secret are set. One without
+ * the other, or a malformed value, fails the boot: an operator who set half
+ * of it meant to turn the feature on.
+ */
+import { z } from 'zod';
+import { isSecureUrl } from '../artifacts/config';
+import { DEFAULT_MODEL_ID } from '../core/llm';
+import type { OracleWorkerEnv } from '../do/contracts';
+import type { FeedbackIssue } from './contract';
+
+/** Studio team and its "User Feedback from Portal" project. */
+export const DEFAULT_FEEDBACK_LINEAR_TEAM_ID =
+  'c781a53a-d432-469f-9c9c-2345a0f8243b';
+export const DEFAULT_FEEDBACK_LINEAR_PROJECT_ID =
+  '6c1474a9-620c-4e3c-b443-0263992f3b55';
+export const DEFAULT_FEEDBACK_LINEAR_API_URL = 'https://api.linear.app/graphql';
+export const FEEDBACK_HMAC_SECRET_MIN_CHARS = 32;
+
+const linearId = z.uuid();
+
+const FeedbackEnv = z.object({
+  FEEDBACK_LINEAR_API_KEY: z.string().trim().min(1),
+  FEEDBACK_HMAC_SECRET: z.string().min(FEEDBACK_HMAC_SECRET_MIN_CHARS),
+  FEEDBACK_LINEAR_TEAM_ID: linearId.default(DEFAULT_FEEDBACK_LINEAR_TEAM_ID),
+  FEEDBACK_LINEAR_PROJECT_ID: linearId.default(
+    DEFAULT_FEEDBACK_LINEAR_PROJECT_ID,
+  ),
+  FEEDBACK_LINEAR_LABEL_IDS: z
+    .string()
+    .optional()
+    .transform((raw) =>
+      (raw ?? '')
+        .split(',')
+        .map((id) => id.trim())
+        .filter(Boolean),
+    )
+    .pipe(z.array(linearId)),
+  FEEDBACK_LINEAR_API_URL: z
+    .string()
+    .refine(isSecureUrl, 'must be an https URL (http only on localhost)')
+    .default(DEFAULT_FEEDBACK_LINEAR_API_URL),
+  QIFORGE_BUILD_VERSION: z.string().trim().min(1).max(80).optional(),
+});
+
+export interface LinearDestination {
+  apiUrl: string;
+  apiKey: string;
+  teamId: string;
+  projectId: string;
+  labelIds: string[];
+}
+
+export interface FeedbackConfig {
+  hmacSecret: string;
+  linear: LinearDestination;
+  /** The coarse Agent context every issue carries. */
+  agent: FeedbackIssue['agent'];
+}
+
+type FeedbackEnvSource = Pick<
+  OracleWorkerEnv,
+  | 'ORACLE_NAME'
+  | 'ORACLE_DID'
+  | 'ORACLE_ENTITY_DID'
+  | 'DEFAULT_MODEL'
+  | 'LLM_PROVIDER'
+  | 'FEEDBACK_LINEAR_API_KEY'
+  | 'FEEDBACK_HMAC_SECRET'
+  | 'FEEDBACK_LINEAR_TEAM_ID'
+  | 'FEEDBACK_LINEAR_PROJECT_ID'
+  | 'FEEDBACK_LINEAR_LABEL_IDS'
+  | 'FEEDBACK_LINEAR_API_URL'
+  | 'QIFORGE_BUILD_VERSION'
+>;
+
+const blank = (value: string | undefined) => !value || !value.trim();
+
+/**
+ * Null when the feature is off. Throws when it is half-configured or a
+ * value is malformed; the message names the keys, never their values.
+ */
+export function feedbackConfigFromEnv(
+  env: FeedbackEnvSource,
+): FeedbackConfig | null {
+  const keyMissing = blank(env.FEEDBACK_LINEAR_API_KEY);
+  const secretMissing = blank(env.FEEDBACK_HMAC_SECRET);
+  if (keyMissing && secretMissing) return null;
+  if (keyMissing || secretMissing)
+    throw new Error(
+      `Anonymous feedback is half-configured: set both FEEDBACK_LINEAR_API_KEY and FEEDBACK_HMAC_SECRET, or neither (missing: ${keyMissing ? 'FEEDBACK_LINEAR_API_KEY' : 'FEEDBACK_HMAC_SECRET'})`,
+    );
+  const parsed = FeedbackEnv.safeParse(env);
+  if (!parsed.success)
+    throw new Error(
+      `Anonymous feedback configuration is invalid: ${parsed.error.issues
+        .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+        .join('; ')}`,
+    );
+  const config = parsed.data;
+  return {
+    hmacSecret: config.FEEDBACK_HMAC_SECRET,
+    linear: {
+      apiUrl: config.FEEDBACK_LINEAR_API_URL,
+      apiKey: config.FEEDBACK_LINEAR_API_KEY,
+      teamId: config.FEEDBACK_LINEAR_TEAM_ID,
+      projectId: config.FEEDBACK_LINEAR_PROJECT_ID,
+      labelIds: config.FEEDBACK_LINEAR_LABEL_IDS,
+    },
+    agent: {
+      did: env.ORACLE_ENTITY_DID || env.ORACLE_DID,
+      name: env.ORACLE_NAME,
+      model: env.DEFAULT_MODEL || DEFAULT_MODEL_ID,
+      provider: env.LLM_PROVIDER ?? 'openrouter',
+      runtimeBuildVersion: config.QIFORGE_BUILD_VERSION ?? 'unknown',
+    },
+  };
+}

package/src/feedback/contract.ts

@@ -0,0 +1,148 @@
+/**
+ * Anonymous Agent-response feedback: the wire contract of
+ * `POST /messages/:sessionId/:messageId/feedback`, the issue handed to a
+ * sink, and the user object's reservation outcomes.
+ *
+ * The request carries free text plus a small allowlisted context. Nothing
+ * else a client sends is read, so no prompt, response, tool data, URL, user
+ * agent or location can reach the sink through this route.
+ */
+import { z } from 'zod';
+
+/**
+ * The env prefix reserved for this feature (its Linear key and pseudonym
+ * secret): `composeEnvSchema` refuses a plugin that declares a key under it.
+ */
+export const FEEDBACK_ENV_PREFIX = 'FEEDBACK_';
+
+export const FEEDBACK_TEXT_MAX_CHARS = 2000;
+/** Generous for 2000 characters of text plus the context; anything larger is not a feedback form. */
+export const FEEDBACK_BODY_MAX_BYTES = 16 * 1024;
+
+/** Language and optional region only (`en`, `en-GB`, `es-419`) — no variants or extensions. */
+const LANGUAGE_REGION = /^[a-z]{2,3}(?:-(?:[A-Z]{2}|\d{3}))?$/;
+
+/**
+ * A BCP 47 tag reduced to its canonical form, accepted only as language plus
+ * optional region. Variants and private-use subtags are free text a client
+ * could fill with a name or a place, so they are refused.
+ */
+const Locale = z
+  .string()
+  .max(35)
+  .transform((raw, ctx) => {
+    let canonical: string | undefined;
+    try {
+      canonical = Intl.getCanonicalLocales(raw)[0];
+    } catch {
+      canonical = undefined;
+    }
+    if (canonical === undefined || !LANGUAGE_REGION.test(canonical)) {
+      ctx.addIssue({
+        code: 'custom',
+        message: 'locale must be a language with an optional region',
+      });
+      return z.NEVER;
+    }
+    return canonical;
+  });
+
+/**
+ * A release (`1.4.0`, `1.5.0-rc.2`, `1.4.0+4f2ea36`) or a commit (`4f2ea36`).
+ * Pre-release labels are a fixed list so the field cannot carry free text.
+ */
+const PORTAL_BUILD =
+  /^(?:\d+\.\d+\.\d+(?:-(?:alpha|beta|rc|next|canary)(?:\.\d+)*)?(?:\+[0-9a-f]{7,12})?|[0-9a-f]{7,40})$/;
+
+export const FeedbackContext = z
+  .object({
+    surface: z.enum(['workspace', 'agentSidebar']),
+    locale: Locale,
+    theme: z.enum(['dark', 'light']),
+    deviceClass: z.enum(['mobile', 'tablet', 'desktop']),
+    viewportBucket: z.enum(['compact', 'medium', 'wide']),
+    network: z.enum(['mainnet', 'testnet', 'devnet', 'unknown']),
+    portalBuildVersion: z.string().max(40).regex(PORTAL_BUILD).optional(),
+  })
+  .strict();
+export type FeedbackContext = z.output<typeof FeedbackContext>;
+
+export const FeedbackSubmission = z
+  .object({
+    /** Client-generated idempotency key: a retry of one submission reuses it. */
+    submissionId: z.uuidv4(),
+    feedback: z.string().min(1).max(FEEDBACK_TEXT_MAX_CHARS),
+    context: FeedbackContext,
+  })
+  .strict();
+export type FeedbackSubmission = z.infer<typeof FeedbackSubmission>;
+
+export interface FeedbackResponse {
+  submissionId: string;
+  status: 'submitted';
+  submittedAt: string;
+}
+
+/** Everything a sink receives. Ids are keyed pseudonyms, never raw values. */
+export interface FeedbackIssue {
+  submissionId: string;
+  /** The screened text — the only user-authored content. */
+  feedback: string;
+  submittedAt: string;
+  userPseudonym: string;
+  sessionFingerprint: string;
+  /** Also the sink's idempotency marker: one issue per user message. */
+  messageFingerprint: string;
+  agent: {
+    did: string;
+    name: string;
+    model: string;
+    provider: string;
+    runtimeBuildVersion: string;
+  };
+  context: FeedbackContext;
+}
+
+/**
+ * `created`: this call made the issue. `existing`: an issue for the message
+ * was already there, so this call sent nothing.
+ */
+export type FeedbackDelivery = 'created' | 'existing';
+
+/**
+ * Where feedback goes. The runtime ships a Linear sink; tests inject a fake.
+ * `submit` must be idempotent per `messageFingerprint`, say whether it
+ * created the issue, and throw when the outcome was not confirmed.
+ */
+export interface FeedbackSink {
+  submit(issue: FeedbackIssue): Promise<FeedbackDelivery>;
+}
+
+/** How the shell settles a reservation (see `FeedbackMarkers.settle`). */
+export type FeedbackSettlement = 'delivered' | 'superseded' | 'released';
+
+/** The message a submission is about, as the shell names it to the user object. */
+export interface FeedbackTarget {
+  sessionId: string;
+  messageId: string;
+  submissionId: string;
+}
+
+/**
+ * What the user object answers when the shell asks to submit feedback:
+ * - `reserved`: deliver now, then settle the reservation.
+ *   `replacesOtherSubmission` is true when it took over a stale reservation
+ *   of a different submission, which may already have created the issue;
+ * - `delivered`: this submission already went out — answer with it again;
+ * - `in_flight`: this same submission is being delivered right now;
+ * - `conflict`: different feedback for the message was delivered or is in flight;
+ * - `not_found`: no such session or message, or not a completed Agent reply;
+ * - `rate_limited`: the user's own submission limit.
+ */
+export type FeedbackReservation =
+  | { kind: 'reserved'; submittedAt: string; replacesOtherSubmission: boolean }
+  | { kind: 'delivered'; submittedAt: string }
+  | { kind: 'in_flight' }
+  | { kind: 'conflict' }
+  | { kind: 'not_found' }
+  | { kind: 'rate_limited' };

package/src/feedback/linear-sink.ts

@@ -0,0 +1,285 @@
+/**
+ * The Linear feedback sink: one issue per (user, message) in the configured
+ * team and project, over Linear's GraphQL API with `fetch`.
+ *
+ * Idempotent across retries and Worker restarts: the issue description
+ * carries the message fingerprint, and the sink looks for it before every
+ * create and again before retrying a create whose outcome is unknown.
+ * Bounded: at most three attempts per call, waits honour Linear's
+ * `X-RateLimit-*-Reset` headers (UTC epoch milliseconds) and give up rather
+ * than wait longer than {@link MAX_RETRY_WAIT_MS}.
+ */
+import type { LinearDestination } from './config';
+import type { FeedbackDelivery, FeedbackIssue, FeedbackSink } from './contract';
+
+const FIND_EXISTING_ISSUE = `
+  query AnonymousFeedbackIssue($projectId: ID!, $marker: String!) {
+    issues(
+      first: 1
+      filter: {
+        project: { id: { eq: $projectId } }
+        description: { contains: $marker }
+      }
+    ) {
+      nodes { id }
+    }
+  }
+`;
+
+const CREATE_FEEDBACK_ISSUE = `
+  mutation CreateAnonymousFeedbackIssue($input: IssueCreateInput!) {
+    issueCreate(input: $input) {
+      success
+      issue { id }
+    }
+  }
+`;
+
+const MAX_ATTEMPTS = 3;
+const MAX_RETRY_WAIT_MS = 2_000;
+const REQUEST_TIMEOUT_MS = 8_000;
+
+/** A failed Linear call. The message holds the status and error code only. */
+export class LinearFeedbackError extends Error {
+  constructor(
+    message: string,
+    readonly retryable: boolean,
+    readonly retryAfterMs?: number,
+  ) {
+    super(message);
+    this.name = 'LinearFeedbackError';
+  }
+}
+
+interface LinearGraphqlResponse<T> {
+  data?: T;
+  errors?: Array<{ extensions?: { code?: string } }>;
+}
+
+export interface LinearSinkOptions {
+  fetch?: typeof fetch;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+}
+
+function tableValue(value: string): string {
+  return value.replace(/[\r\n|]/g, ' ').trim() || 'unknown';
+}
+
+/**
+ * The user's text as a fenced block, so Linear renders it verbatim: no
+ * headings, links or images (an image would fetch from a URL the author
+ * chose when a reviewer opens the issue), no fake context table. The fence
+ * is one backtick longer than any run in the text, so the text cannot close
+ * it.
+ */
+function fencedText(text: string): string {
+  const longestRun = Math.max(
+    2,
+    ...Array.from(text.matchAll(/`+/g), (m) => m[0].length),
+  );
+  const fence = '`'.repeat(longestRun + 1);
+  return `${fence}text\n${text}\n${fence}`;
+}
+
+/**
+ * How long a RATE-LIMITED response asks us to wait. Linear sends the
+ * `X-RateLimit-*-Reset` headers on every response, so they say when the
+ * window resets, not when to retry a failure: they are only read for a
+ * rate limit (HTTP 429 or GraphQL `RATELIMITED`). Other failures back off.
+ */
+function rateLimitDelayMs(response: Response, now: number): number | undefined {
+  const retryAfter = response.headers.get('retry-after');
+  if (retryAfter) {
+    const seconds = Number(retryAfter);
+    if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
+    const date = Date.parse(retryAfter);
+    if (Number.isFinite(date)) return Math.max(0, date - now);
+  }
+  const reset =
+    response.headers.get('x-ratelimit-endpoint-requests-reset') ??
+    response.headers.get('x-ratelimit-requests-reset') ??
+    response.headers.get('x-ratelimit-complexity-reset');
+  const resetAt = reset ? Number(reset) : Number.NaN;
+  return Number.isFinite(resetAt) ? Math.max(0, resetAt - now) : undefined;
+}
+
+export function linearFeedbackTitle(issue: FeedbackIssue): string {
+  const at = new Date(issue.submittedAt)
+    .toISOString()
+    .replace(/\.\d{3}Z$/, 'Z');
+  return `[Agent feedback] ${issue.context.surface} · ${at}`;
+}
+
+/**
+ * The issue body: the screened feedback, then a table of allowlisted coarse
+ * context and keyed pseudonyms. Nothing else about the user or the
+ * conversation is available to this function.
+ */
+export function linearFeedbackDescription(issue: FeedbackIssue): string {
+  const rows: Array<[string, string]> = [
+    ['Submission ID', issue.submissionId],
+    ['User pseudonym', issue.userPseudonym],
+    ['Session fingerprint', issue.sessionFingerprint],
+    ['Message fingerprint', issue.messageFingerprint],
+    ['Agent DID', issue.agent.did],
+    ['Agent name', issue.agent.name],
+    ['Default model', issue.agent.model],
+    ['Provider', issue.agent.provider],
+    ['Surface', issue.context.surface],
+    ['Network', issue.context.network],
+    ['Locale', issue.context.locale],
+    ['Theme', issue.context.theme],
+    ['Device class', issue.context.deviceClass],
+    ['Viewport', issue.context.viewportBucket],
+    ['Portal build', issue.context.portalBuildVersion ?? 'unknown'],
+    ['QiForge build', issue.agent.runtimeBuildVersion],
+    ['Submitted at', issue.submittedAt],
+  ];
+  return [
+    '## Feedback',
+    '',
+    fencedText(issue.feedback),
+    '',
+    '## Safe context',
+    '',
+    '| Field | Value |',
+    '| --- | --- |',
+    ...rows.map(([label, value]) => `| ${label} | ${tableValue(value)} |`),
+    '',
+    '## Privacy',
+    '',
+    'No prompt, response, reasoning, tool data, attachment, raw DID, raw session ID, raw message ID, IP address, URL, payment data, location or full user agent was attached. User and conversation references are keyed pseudonyms.',
+  ].join('\n');
+}
+
+export class LinearFeedbackSink implements FeedbackSink {
+  private readonly fetch: typeof fetch;
+  private readonly sleep: (ms: number) => Promise<void>;
+  private readonly now: () => number;
+
+  constructor(
+    private readonly destination: LinearDestination,
+    opts: LinearSinkOptions = {},
+  ) {
+    this.fetch = opts.fetch ?? ((input, init) => fetch(input, init));
+    this.sleep =
+      opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    this.now = opts.now ?? Date.now;
+  }
+
+  async submit(issue: FeedbackIssue): Promise<FeedbackDelivery> {
+    const marker = issue.messageFingerprint;
+    if (await this.issueExists(marker)) return 'existing';
+    const { teamId, projectId, labelIds } = this.destination;
+    const input = {
+      teamId,
+      projectId,
+      title: linearFeedbackTitle(issue),
+      description: linearFeedbackDescription(issue),
+      ...(labelIds.length > 0 && { labelIds }),
+    };
+    for (let attempt = 0; ; attempt += 1) {
+      try {
+        const created = await this.requestOnce<{
+          issueCreate: { success: boolean; issue?: { id: string } | null };
+        }>(CREATE_FEEDBACK_ISSUE, { input });
+        if (!created.issueCreate.success || !created.issueCreate.issue?.id)
+          throw new LinearFeedbackError(
+            'Linear did not confirm the feedback issue',
+            false,
+          );
+        return 'created';
+      } catch (error) {
+        if (
+          !(error instanceof LinearFeedbackError) ||
+          !error.retryable ||
+          attempt === MAX_ATTEMPTS - 1
+        )
+          throw error;
+        await this.waitBeforeRetry(error, attempt);
+        // The failed create may have landed: never create a second issue.
+        // It was this call's create, so it counts as created.
+        if (await this.issueExists(marker)) return 'created';
+      }
+    }
+  }
+
+  private async issueExists(marker: string): Promise<boolean> {
+    for (let attempt = 0; ; attempt += 1) {
+      try {
+        const found = await this.requestOnce<{
+          issues: { nodes: Array<{ id: string }> };
+        }>(FIND_EXISTING_ISSUE, {
+          projectId: this.destination.projectId,
+          marker,
+        });
+        return found.issues.nodes.length > 0;
+      } catch (error) {
+        if (
+          !(error instanceof LinearFeedbackError) ||
+          !error.retryable ||
+          attempt === MAX_ATTEMPTS - 1
+        )
+          throw error;
+        await this.waitBeforeRetry(error, attempt);
+      }
+    }
+  }
+
+  private async waitBeforeRetry(
+    error: LinearFeedbackError,
+    attempt: number,
+  ): Promise<void> {
+    const delay = error.retryAfterMs ?? 250 * 2 ** attempt;
+    if (delay > MAX_RETRY_WAIT_MS) throw error;
+    await this.sleep(delay);
+  }
+
+  private async requestOnce<T>(
+    query: string,
+    variables: Record<string, unknown>,
+  ): Promise<T> {
+    let response: Response;
+    try {
+      response = await this.fetch(this.destination.apiUrl, {
+        method: 'POST',
+        // Linear personal API keys go in the header as-is (no Bearer prefix).
+        headers: {
+          authorization: this.destination.apiKey,
+          'content-type': 'application/json',
+        },
+        body: JSON.stringify({ query, variables }),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      });
+    } catch (error) {
+      throw new LinearFeedbackError(
+        error instanceof Error &&
+          (error.name === 'TimeoutError' || error.name === 'AbortError')
+          ? 'Linear feedback request timed out'
+          : 'Linear feedback request failed (network)',
+        true,
+      );
+    }
+    const payload: LinearGraphqlResponse<T> | null = await response
+      .json<LinearGraphqlResponse<T>>()
+      .catch(() => null);
+    const code = payload?.errors?.[0]?.extensions?.code;
+    if (!response.ok || payload?.errors?.length) {
+      const rateLimited = response.status === 429 || code === 'RATELIMITED';
+      throw new LinearFeedbackError(
+        `Linear feedback request failed (${response.status}${code ? `/${code}` : ''})`,
+        rateLimited ||
+          response.status >= 500 ||
+          code === 'INTERNAL_SERVER_ERROR',
+        rateLimited ? rateLimitDelayMs(response, this.now()) : undefined,
+      );
+    }
+    if (!payload?.data)
+      throw new LinearFeedbackError(
+        'Linear feedback request returned no data',
+        false,
+      );
+    return payload.data;
+  }
+}