@volter/twin-openai 0.1.2 → 2.0.1

package/src/openai-types.ts

@@ -24,7 +24,8 @@ export type ChatUsage = {
   prompt_tokens: number;
   completion_tokens: number;
   total_tokens: number;
-  completion_tokens_details?: { accepted_prediction_tokens: number; rejected_prediction_tokens: number };
+  prompt_tokens_details?: { cached_tokens: number; audio_tokens: number };
+  completion_tokens_details?: { reasoning_tokens: number; audio_tokens: number; accepted_prediction_tokens: number; rejected_prediction_tokens: number };
 };
 
 /** A per-token logprob entry (faithful `choices[].logprobs.content[]` shape). */
@@ -42,7 +43,7 @@ export type ChatAudioOutput = { id: string; data: string; transcript: string; ex
 
 export type ChatChoice = {
   index: number;
-  message: { role: 'assistant'; content: string | null; tool_calls?: ChatToolCall[]; refusal?: null; audio?: ChatAudioOutput };
+  message: { role: 'assistant'; content: string | null; tool_calls?: ChatToolCall[]; refusal?: null; annotations?: unknown[]; audio?: ChatAudioOutput };
   logprobs: { content: ChatLogprobToken[] } | null;
   finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter';
 };
@@ -56,6 +57,7 @@ export type ChatCompletion = {
   choices: ChatChoice[];
   usage: ChatUsage;
   system_fingerprint: string;
+  service_tier?: string;
   metadata?: Record<string, unknown> | null;
 };
 
@@ -66,7 +68,7 @@ export type ResponseMessageItem = {
   id: string;
   status: 'completed';
   role: 'assistant';
-  content: Array<{ type: 'output_text'; text: string; annotations: unknown[] }>;
+  content: Array<{ type: 'output_text'; text: string; annotations: unknown[]; logprobs?: unknown[] }>;
 };
 /** A reasoning output item (emitted for reasoning models / when `reasoning.effort` is set). The
  *  twin can't run the model, so the reasoning `summary` is a clearly-labeled stub; the item SHAPE
@@ -76,7 +78,21 @@ export type ResponseReasoningItem = {
   id: string;
   summary: Array<{ type: 'summary_text'; text: string }>;
 };
-export type ResponseOutputItem = ResponseMessageItem | ResponseReasoningItem;
+/** A function-call output item: the model asking for a tool, as the Responses API shapes it
+ *  (`call_id` pairs with the caller's later `function_call_output` input item; `arguments` is JSON text). */
+export type ResponseFunctionCallItem = {
+  type: 'function_call';
+  id: string;
+  status: 'completed';
+  call_id: string;
+  name: string;
+  arguments: string;
+};
+/** A built-in tool OpenAI ran for the response: a web search or a file search (the spec's WebSearchToolCall, FileSearchToolCall). */
+export type ResponseBuiltInCallItem =
+  | { type: 'web_search_call'; id: string; status: 'completed'; action: { type: 'search'; query: string } }
+  | { type: 'file_search_call'; id: string; status: 'completed'; queries: string[]; results: null };
+export type ResponseOutputItem = ResponseMessageItem | ResponseReasoningItem | ResponseFunctionCallItem | ResponseBuiltInCallItem;
 
 /** The Responses API usage object — `output_tokens_details.reasoning_tokens` reports tokens spent
  *  on the (stubbed) reasoning item, faithful to the vendor shape. */
@@ -84,6 +100,7 @@ export type ResponseUsage = {
   input_tokens: number;
   output_tokens: number;
   total_tokens: number;
+  input_tokens_details?: { cached_tokens: number; cache_write_tokens: number };
   output_tokens_details?: { reasoning_tokens: number };
 };
 
@@ -97,8 +114,9 @@ export type OpenAIResponse = {
   output: ResponseOutputItem[];
   output_text?: string;
   usage: ResponseUsage;
-  reasoning?: { effort: string; summary: string | null };
-  previous_response_id?: string;
+  completed_at?: number | null;
+  reasoning?: { effort: string | null; summary: string | null };
+  previous_response_id?: string | null;
 };
 
 // ── Embeddings ──────────────────────────────────────────────────────────────────────────

package/src/openai-webhooks.ts

@@ -1,3 +1,4 @@
+import { nodeBuiltin, worldNow } from '@volter/world-core';
 // OpenAI webhooks — REAL HMAC-signed delivery, Standard-Webhooks scheme.
 //
 // Real OpenAI delivers asynchronous job-completion notifications (batch / fine-tuning /
@@ -13,7 +14,7 @@
 type NodeCrypto = typeof import('node:crypto');
 function nodeCrypto(): NodeCrypto {
   // eslint-disable-next-line @typescript-eslint/no-require-imports
-  return require('node:crypto') as NodeCrypto;
+  return nodeBuiltin('node:crypto') as NodeCrypto;
 }
 
 /** The thin webhook envelope OpenAI POSTs: { object:'event', id, type, created_at, data:{id} }. */
@@ -63,7 +64,7 @@ export function verifyOpenAIWebhook(payload: string, headers: Record<string, str
   const sigHeader = lower['webhook-signature'];
   if (!id || !sigHeader || !Number.isFinite(ts)) throw new OpenAIWebhookVerificationError('Missing required webhook headers (webhook-id / webhook-timestamp / webhook-signature).');
   if (opts.tolerance !== undefined) {
-    const now = opts.now ?? Math.floor(Date.now() / 1000);
+    const now = opts.now ?? Math.floor(Date.parse(worldNow()) / 1000);
     if (Math.abs(now - ts) > opts.tolerance) throw new OpenAIWebhookVerificationError('Webhook timestamp outside tolerance.');
   }
   const expected = computeOpenAIWebhookSignature(id, ts, payload, secret).slice('v1,'.length);

package/src/screens/api-keys.tsx

@@ -0,0 +1,138 @@
+// OPENAI'S API KEYS PAGE — a workspace screen (docs/contributing/architecture.md, "Screens"): a project's secret keys
+// are made on platform.openai.com, never through the API (docs: platform.openai.com/docs/api-reference/project-api-keys
+// lists, retrieves and deletes them; creating one is the dashboard's "Create new secret key"). The page lists the
+// project's keys, makes a new one from its name and permissions and shows its secret once, and revokes a key. The
+// Admin API then reads and deletes what the page made. Authored from @volter/world-ui's portal piece under OpenAI's
+// skin; nothing of OpenAI's page is copied.
+//
+// The page acts for the person signed in to the dashboard (./session.tsx), never on an API key: a key is for the API,
+// and a request whose session names nobody is sent to log in. A key the page makes is that person's: its owner is
+// their user (https://platform.openai.com/docs/api-reference/project-api-keys/object, owner.user: id, email, name,
+// created_at, role).
+//
+// Where the documentation stops and the twin decides: a key's secret is derived from its id, and shown once, as the
+// dashboard does; any person of the organization may make and revoke a project's keys.
+import { createHash } from 'node:crypto';
+import { semanticsContext, vendorError, type SemanticsContext } from '@volter/world-core';
+import { flowPage, Portal, PORTAL_CSS } from '@volter/world-ui';
+import surface from '../generated/surface.gen.json' with { type: 'json' };
+import { manifest } from '../manifest.ts';
+import { epoch } from '../semantics/shared.ts';
+import { signedIn, toLogIn, type Account } from './session.tsx';
+
+const KEY = 'ProjectApiKey';
+const OPERATION = (surface.operations as Array<{ id: string; method: string; path: string; class: string }>).find((o) => o.id === 'list-project-api-keys')!;
+// a key's owner as the spec's ProjectApiKeyOwnerUser gives it: the person's user, created_at being when they joined, and
+// role their role in the project, "owner" or "member" (https://platform.openai.com/docs/api-reference/project-users/object).
+// The twin keeps no project members: the organization's owner owns every project, and anyone else who makes a key there
+// is a member of it.
+const ownerOf = (person: Account): Record<string, unknown> => ({ id: person.id, email: person.email, name: person.name, created_at: person.added_at, role: person.role === 'owner' ? 'owner' : 'member' });
+const PERMISSIONS = [{ value: 'all', label: 'All' }, { value: 'restricted', label: 'Restricted' }, { value: 'read_only', label: 'Read only' }];
+
+const OPENAI_SKIN = `
+body { background: #ffffff; color: #0d0d0d; font-family: "Söhne", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; }
+.portal-side { background: #f9f9f9; border-right: 1px solid #ececec; }
+.portal-section h2 { border-color: #ececec; color: #5d5d5d; }
+.portal-notice { background: #f0fdf4; border: 1px solid #bbf7d0; }
+.portal-detail, .portal-note { color: #5d5d5d; }
+.portal-button { border-color: #d9d9d9; color: #0d0d0d; }
+.portal-primary { background: #0d0d0d; border-color: #0d0d0d; color: #ffffff; }
+.portal-danger { color: #d00e17; border-color: #f3b4b7; }
+.portal-field input, .portal-field select { border-color: #d9d9d9; }
+`;
+const css = [PORTAL_CSS, OPENAI_SKIN];
+
+const secretOf = (id: string): string => `sk-proj-${createHash('sha256').update(`project-key:${id}`).digest('hex').slice(0, 48)}`;
+const redacted = (secret: string): string => `${secret.slice(0, 11)}...${secret.slice(-4)}`;
+
+/** The fields a submission carries: the page's form, as a browser posts it. */
+async function formOf(request: Request): Promise<Record<string, string>> {
+  return Object.fromEntries(new URLSearchParams(await request.text()));
+}
+
+function page(ctx: SemanticsContext, project: Record<string, unknown>, notice?: string, status = 200): Response {
+  const id = String(project.id);
+  const keys = ctx.rowsRaw(KEY).filter((k) => k._project_id === id).sort((a, b) => Number(b.created_at) - Number(a.created_at));
+  const action = `/settings/${id}/api-keys`;
+  return flowPage({
+    title: 'API keys - OpenAI API',
+    status,
+    css,
+    body: (
+      <Portal
+        merchant="OpenAI Platform"
+        back={{ href: '/settings/organization/general', label: String(project.name) }}
+        {...(notice ? { notice } : {})}
+        sections={[{
+          heading: 'API keys',
+          empty: 'This project has no API keys yet.',
+          items: keys.map((k) => ({
+            title: String(k.name),
+            detail: String(k.redacted_value),
+            note: `Created ${new Date(Number(k.created_at) * 1000).toISOString().slice(0, 10)} by ${String((k.owner as { user?: { name?: string } } | undefined)?.user?.name ?? '')}`,
+            actions: [{ label: 'Revoke key', action, fields: { revoke: String(k.id) }, tone: 'danger' as const }],
+          })),
+        }]}
+        forms={[{
+          heading: 'Create new secret key',
+          action,
+          fields: [
+            { id: 'name', label: 'Name', placeholder: 'My Test Key' },
+            { id: 'permissions', label: 'Permissions', options: PERMISSIONS, value: 'all' },
+          ],
+          submit: { label: 'Create secret key' },
+        }]}
+      />
+    ),
+  });
+}
+
+/** A request that presents one of the organization's project keys uses it: the key's `last_used_at` is that instant
+ *  (https://platform.openai.com/docs/api-reference/project-api-keys/object, "The Unix timestamp (in seconds) of when the
+ *  API key was last used."). A key that has stopped working is refused: one revoked on the keys page or deleted through the
+ *  Admin API, and one of an archived project ("Archived projects cannot be used or updated",
+ *  https://platform.openai.com/docs/api-reference/projects/archive). The refusal is OpenAI's incorrect-key answer (the
+ *  manifest's `auth.invalid`), as OpenAI documents no other for them; the answer is that refusal, or nothing to let the
+ *  request on. */
+export function projectKeyUse(scope: { root?: string; clock?: () => string }): (request: Request) => Promise<Response | undefined> {
+  return async (request) => {
+    const bearer = /^Bearer\s+(sk-proj-\S+)$/i.exec(request.headers.get('authorization') ?? '')?.[1];
+    if (!bearer) return undefined;
+    const ctx = await semanticsContext(manifest, new Request(request.url, { headers: request.headers }), OPERATION, scope);
+    const key = ctx.rowsRaw(KEY, { withDeleted: true }).find((k) => secretOf(String(k.id)) === bearer);
+    const archived = key ? ctx.row('Project', String(key._project_id))?.status === 'archived' : false;
+    if (key?.deleted === true || archived) return vendorError(manifest, manifest.auth!.invalid);
+    if (key) await ctx.write(KEY, String(key.id), { last_used_at: epoch(ctx) }, 'api_key.update');
+    return undefined;
+  };
+}
+
+/** platform.openai.com/settings/{project}/api-keys, or undefined for any other request. */
+
+export function openaiApiKeysScreen(scope: { root?: string; clock?: () => string }): (request: Request) => Promise<Response | undefined> {
+  return async (request) => {
+    const m = /^\/settings\/(proj[-_][A-Za-z0-9_-]+)\/api-keys\/?$/.exec(new URL(request.url).pathname);
+    if (!m || (request.method !== 'GET' && request.method !== 'POST')) return undefined;
+    const form = request.method === 'POST' ? await formOf(request.clone()) : {};
+    const ctx = await semanticsContext(manifest, request, OPERATION, scope);
+    const person = signedIn(request, ctx);
+    if (!person) return toLogIn(request);
+    const project = ctx.get('Project', m[1]!);
+    if (!project) return flowPage({ title: 'OpenAI Platform', status: 404, css, body: <main className="portal-main"><h1>Project not found</h1></main> });
+    if (request.method === 'GET') return page(ctx, project);
+    if (form.revoke) {
+      const key = ctx.row(KEY, form.revoke);
+      if (!key || key._project_id !== project.id) return page(ctx, project, 'That key no longer exists.', 404);
+      await ctx.write(KEY, form.revoke, { deleted: true }, 'api_key.delete');
+      return page(ctx, project, `Revoked ${String(key.name)}. Requests using it will now fail.`);
+    }
+    const name = (form.name ?? '').trim() || 'Secret key';
+    const id = ctx.mint(KEY);
+    const secret = secretOf(id);
+    await ctx.write(KEY, id, {
+      object: 'organization.project.api_key', name, redacted_value: redacted(secret), created_at: epoch(ctx), last_used_at: null,
+      _project_id: project.id, owner: { type: 'user', user: ownerOf(person) }, owner_project_access: 'active', _permissions: PERMISSIONS.some((p) => p.value === form.permissions) ? form.permissions : 'all',
+    }, 'api_key.create');
+    return page(ctx, project, `Save your key: ${secret}. You won't be able to view it again.`, 201);
+  };
+}

package/src/screens/session.tsx

@@ -0,0 +1,131 @@
+// OPENAI'S LOG-IN — the door before the dashboard's pages (docs/contributing/architecture.md, "Who is on a screen"): the
+// log-in page takes a person's email address and password, the right pair signs them in, and the dashboard's session
+// cookie names them to every page after. A dashboard page asked for by nobody signed in sends its visitor to the log-in
+// with `return_to`, and the log-in returns them there. Built from @volter/world-ui's sign-in piece under OpenAI's skin;
+// nothing of OpenAI's page is copied.
+//
+// A person is an account of the World's organization, as the Admin API's user object gives one
+// (https://platform.openai.com/docs/api-reference/users/object: id, name, email, role "owner" or "reader", added_at).
+//
+// Where OpenAI's documentation stops and the twin decides: an account is made at the World's door
+// (`POST /_twin/accounts`, standing in for OpenAI's sign-up, which is not modelled), and the World keeps its password's
+// hash, never the password; the World has one organization, whose first account is its owner and whose later ones join
+// as readers unless the door names a role; the log-in is one page (OpenAI's asks for the email and the password on two),
+// served on the dashboard's own host at platform.openai.com/login, the address OpenAI's log-in link opens (OpenAI hands it
+// on to auth.openai.com, which the twin does not model as a host of its own), so its session cookie is the dashboard's;
+// the session cookie's name (`platform_session`) is the twin's, as OpenAI documents none; a refused log-in shows the page
+// again with the message, answered 200; and a session does not end: no person of a World logs out yet.
+import { createHash } from 'node:crypto';
+import { semanticsContext, type SemanticsContext } from '@volter/world-core';
+import { cookieOf, flowPage, SignIn, SIGN_IN_CSS } from '@volter/world-ui';
+import surface from '../generated/surface.gen.json' with { type: 'json' };
+import { manifest } from '../manifest.ts';
+import { epoch } from '../semantics/shared.ts';
+
+type Scope = { root?: string; clock?: () => string };
+/** A person's account: the user object's fields, and the hash of the password the World gave them. */
+export type Account = { id: string; object: 'organization.user'; name: string; email: string; role: 'owner' | 'reader'; added_at: number; _hash: string };
+
+const ACCOUNT = '_account';
+const SESSION = '_session';
+const COOKIE = 'platform_session';
+const OPERATION = (surface.operations as Array<{ id: string; method: string; path: string; class: string }>).find((o) => o.id === 'retrieve-user')!;
+const hex = (s: string): string => createHash('sha256').update(s).digest('hex');
+const passwordHash = (email: string, password: string): string => hex(`password:${email.toLowerCase()}:${password}`);
+
+// OpenAI's skin over the sign-in: its black primary button on white
+const SKIN = `
+body { background: #ffffff; color: #0d0d0d; font-family: "Söhne", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; }
+.sign-in-mark { background: #0d0d0d; }
+.sign-in-error { background: #fef2f2; border-color: #fecaca; color: #b91c1c; }
+.sign-in-box { background: #ffffff; border-color: #ececec; }
+.sign-in-box input[type=text], .sign-in-box input[type=password] { border-color: #d9d9d9; }
+.sign-in-submit { background: #0d0d0d; border-color: #0d0d0d; color: #ffffff; }
+`;
+
+const contextOf = (request: Request, scope: Scope): Promise<SemanticsContext> => semanticsContext(manifest, request, OPERATION, scope);
+const accounts = (ctx: SemanticsContext): Account[] => ctx.rowsRaw(ACCOUNT) as unknown as Account[];
+
+/** The account the request's session cookie names, or undefined when nobody is signed in. */
+export function signedIn(request: Request, ctx: SemanticsContext): Account | undefined {
+  const token = cookieOf(request, COOKIE);
+  const session = token ? ctx.rowsRaw(SESSION).find((s) => s.token === token) : undefined;
+  return session ? accounts(ctx).find((a) => a.id === session.account) : undefined;
+}
+
+/** Where a dashboard page asked for by nobody signed in sends its visitor: the log-in, returning here after. */
+export function toLogIn(request: Request): Response {
+  const url = new URL(request.url);
+  return new Response(null, { status: 302, headers: { location: `/login?return_to=${encodeURIComponent(url.pathname + url.search)}` } });
+}
+
+/** A return_to the log-in follows: a path on the dashboard, never another site. */
+const returnTo = (raw: string | null | undefined): string => (raw && raw.startsWith('/') && !raw.startsWith('//') ? raw : '/');
+
+function page(back: string, email?: string, error?: string): Response {
+  return flowPage({
+    title: 'Log in - OpenAI',
+    css: [SIGN_IN_CSS, SKIN],
+    body: (
+      <SignIn
+        heading="Welcome back"
+        action="/login"
+        fields={{ return_to: back }}
+        account={{ name: 'email', label: 'Email address', ...(email ? { value: email } : {}) }}
+        password={{ name: 'password', label: 'Password' }}
+        submit="Continue"
+        {...(error ? { error } : {})}
+      />
+    ),
+  });
+}
+
+async function logIn(request: Request, scope: Scope): Promise<Response> {
+  const form = Object.fromEntries(new URLSearchParams(await request.clone().text()));
+  const email = (form.email ?? '').trim();
+  const back = returnTo(form.return_to);
+  const ctx = await contextOf(request, scope);
+  const account = accounts(ctx).find((a) => a.email.toLowerCase() === email.toLowerCase());
+  // the log-in names neither which half was wrong
+  if (!account || account._hash !== passwordHash(account.email, form.password ?? '')) return page(back, email, 'Wrong email or password.');
+  const n = ctx.rowsRaw(SESSION).length + 1;
+  const token = hex(`session:${account.id}:${ctx.occurredAt}:${n}`).slice(0, 48);
+  await ctx.record(SESSION, { token, account: account.id, created_at: epoch(ctx) }, `session_${token.slice(0, 16)}`);
+  return new Response(null, { status: 302, headers: { location: back, 'set-cookie': `${COOKIE}=${token}; path=/; HttpOnly; Secure; SameSite=Lax` } });
+}
+
+/** The World's account door refusing an account it cannot make: one already made for the email, or one missing a field. */
+function badAccount(email: string, taken: boolean): Response {
+  return Response.json({ error: { message: taken ? `An account for ${email} already exists.` : 'An account needs an email address, a name and a password; a role is "owner" or "reader".', type: 'invalid_request_error' } }, { status: 400 });
+}
+
+/** POST /_twin/accounts {email, name, password, role?} → 201 the account's user object: a person of the World's
+ *  organization, who logs in with that password. */
+async function makeAccount(request: Request, scope: Scope): Promise<Response> {
+  let body: Record<string, unknown> = {};
+  try { body = await request.clone().json() as Record<string, unknown>; } catch { /* answered below */ }
+  const email = typeof body.email === 'string' ? body.email.trim() : '';
+  const name = typeof body.name === 'string' ? body.name.trim() : '';
+  const password = typeof body.password === 'string' ? body.password : '';
+  const ctx = await contextOf(request, scope);
+  const taken = accounts(ctx).some((a) => a.email.toLowerCase() === email.toLowerCase());
+  if (!/^[^@\s]+@[^@\s]+$/.test(email) || !name || !password || taken || (body.role !== undefined && body.role !== 'owner' && body.role !== 'reader')) return badAccount(email, taken);
+  const role = (body.role as Account['role'] | undefined) ?? (accounts(ctx).some((a) => a.role === 'owner') ? 'reader' : 'owner');
+  const id = `user-${hex(`account:${email.toLowerCase()}`).slice(0, 24)}`;
+  const account: Account = { id, object: 'organization.user', name, email, role, added_at: epoch(ctx), _hash: passwordHash(email, password) };
+  await ctx.record(ACCOUNT, account, id);
+  const { _hash: _secret, ...user } = account;
+  return Response.json(user, { status: 201 });
+}
+
+/** The log-in's paths and the World's account door, or undefined for any other request. */
+export function openaiSessionFlow(scope: Scope): (request: Request) => Promise<Response | undefined> {
+  return async (request) => {
+    const url = new URL(request.url);
+    const path = url.pathname.replace(/\/+$/, '');
+    if (path === '/login' && request.method === 'GET') return page(returnTo(url.searchParams.get('return_to')));
+    if (path === '/login' && request.method === 'POST') return logIn(request, scope);
+    if (path === '/_twin/accounts' && request.method === 'POST') return makeAccount(request, scope);
+    return undefined;
+  };
+}