@oxy.so/core 1.0.0 → 1.1.1

package/src/mixins/__tests__/OxyServices.serviceLinkedDownloadUrl.test.ts

@@ -0,0 +1,139 @@
+/**
+ * `getServiceLinkedDownloadUrls` mixin tests.
+ *
+ * Stubs `makeServiceRequest` (the service-token transport the route's
+ * `serviceAuthMiddleware` + `files:linked:read` scope require) so these run with
+ * no network and no `getServiceToken()` round-trip.
+ *
+ * The contract worth guarding here is not the transport — the metadata sibling
+ * already pins that shape — it is the TWO absences this method has to keep
+ * distinguishable, because conflating them misinforms a person who paid money:
+ *
+ *   - The server OMITS an id it will not mint for, with no way to tell "no such
+ *     file" from "not yours". That is a legitimate short result, and the caller
+ *     has to map by `id`.
+ *   - A FAILED chunk is not that. It throws, with no `{ partial: true }` escape
+ *     hatch, because the sibling's best-effort mode would make a 429
+ *     indistinguishable from the refusal above.
+ */
+
+import type { ServiceLinkedDownloadUrl } from '../../models/interfaces';
+import { OxyServices } from '../../OxyServices';
+import { ServiceLinkedDownloadUrlError } from '../../OxyServices.errors';
+
+const sampleEntry: ServiceLinkedDownloadUrl = {
+  id: 'asset-1',
+  url: 'https://s3.example/private/asset-1.stl?X-Amz-Signature=deadbeef',
+  expiresIn: 300,
+  mime: 'model/stl',
+  size: 4096,
+  sha256: 'a'.repeat(64),
+};
+
+describe('OxyServices.assets — getServiceLinkedDownloadUrls', () => {
+  let oxy: OxyServices;
+  let makeServiceRequestSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeServiceRequestSpy = jest.spyOn(oxy, 'makeServiceRequest');
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('returns [] and performs no network call for empty / whitespace input', async () => {
+    await expect(oxy.getServiceLinkedDownloadUrls([])).resolves.toEqual([]);
+    await expect(oxy.getServiceLinkedDownloadUrls(['', '   '])).resolves.toEqual([]);
+    expect(makeServiceRequestSpy).not.toHaveBeenCalled();
+  });
+
+  it('POSTs de-duplicated ids to /assets/service/linked-url as { ids }', async () => {
+    makeServiceRequestSpy.mockResolvedValueOnce([sampleEntry]);
+
+    await oxy.getServiceLinkedDownloadUrls(['asset-1', 'asset-1', '  ']);
+
+    expect(makeServiceRequestSpy).toHaveBeenCalledTimes(1);
+    expect(makeServiceRequestSpy).toHaveBeenCalledWith(
+      'POST',
+      '/assets/service/linked-url',
+      { ids: ['asset-1'] },
+    );
+  });
+
+  it('returns entries untouched, so expiresIn and url reach the caller as sent', async () => {
+    makeServiceRequestSpy.mockResolvedValueOnce([sampleEntry]);
+
+    const [entry] = await oxy.getServiceLinkedDownloadUrls(['asset-1']);
+
+    expect(entry).toEqual(sampleEntry);
+  });
+
+  it('chunks at 25, a QUARTER of the metadata route\'s 100', async () => {
+    // The cap is the route's, and the two routes deliberately differ: this one
+    // mints a credential per id. A client chunking at 100 would 400 every call.
+    const ids = Array.from({ length: 26 }, (_, index) => `asset-${index}`);
+    makeServiceRequestSpy.mockResolvedValue([]);
+
+    await oxy.getServiceLinkedDownloadUrls(ids);
+
+    expect(makeServiceRequestSpy).toHaveBeenCalledTimes(2);
+    const sent = makeServiceRequestSpy.mock.calls.map(
+      (call) => (call[2] as { ids: string[] }).ids.length,
+    );
+    expect(sent.sort((a, b) => b - a)).toEqual([25, 1]);
+  });
+
+  it('accepts a SHORT result without complaint — an omitted id is a refusal', async () => {
+    // The server gives no URL for a file the owner did not link here, and says so
+    // by saying nothing. A method that treated a short result as an error would
+    // make the normal case throw.
+    makeServiceRequestSpy.mockResolvedValueOnce([sampleEntry]);
+
+    const entries = await oxy.getServiceLinkedDownloadUrls(['asset-1', 'asset-refused']);
+
+    expect(entries.map((entry) => entry.id)).toEqual(['asset-1']);
+  });
+
+  it('THROWS on a failed chunk, naming its ids', async () => {
+    const failure = Object.assign(new Error('Too Many Requests'), {
+      response: { status: 429 },
+    });
+    makeServiceRequestSpy.mockRejectedValueOnce(failure);
+
+    await expect(oxy.getServiceLinkedDownloadUrls(['asset-1'])).rejects.toThrow(
+      ServiceLinkedDownloadUrlError,
+    );
+
+    makeServiceRequestSpy.mockRejectedValueOnce(failure);
+    const error = await oxy
+      .getServiceLinkedDownloadUrls(['asset-1'])
+      .catch((caught: unknown) => caught as ServiceLinkedDownloadUrlError);
+
+    expect(error.unresolvedIds).toEqual(['asset-1']);
+    expect(error.statuses).toEqual([429]);
+    expect(error.code).toBe('SERVICE_LINKED_DOWNLOAD_URL_UNRESOLVED');
+  });
+
+  it('throws even when OTHER chunks succeeded — a partial answer is not an answer', async () => {
+    // The inverse of the sibling's `{ partial: true }`. Returning the 25 that
+    // worked and dropping the one that did not is exactly how a buyer is told a
+    // file they own is missing, so there is no option to ask for it.
+    const ids = Array.from({ length: 26 }, (_, index) => `asset-${index}`);
+    makeServiceRequestSpy
+      .mockResolvedValueOnce([sampleEntry])
+      .mockRejectedValueOnce(new Error('boom'));
+
+    await expect(oxy.getServiceLinkedDownloadUrls(ids)).rejects.toThrow(
+      ServiceLinkedDownloadUrlError,
+    );
+  });
+
+  it('has no partial option at all', async () => {
+    // Asserted on the ARITY rather than by passing an option and watching it be
+    // ignored: a future signature that quietly accepted `{ partial: true }` would
+    // restore the behaviour this method exists to refuse.
+    expect(oxy.getServiceLinkedDownloadUrls.length).toBe(1);
+  });
+});

package/src/mixins/__tests__/agency.test.ts

@@ -0,0 +1,120 @@
+import { OxyServices } from '../../OxyServices';
+
+function makeJwt(payload: Record<string, unknown>): string {
+  const encode = (value: Record<string, unknown>): string =>
+    Buffer.from(JSON.stringify(value)).toString('base64url');
+  return `${encode({ alg: 'none', typ: 'JWT' })}.${encode({ exp: Math.floor(Date.now() / 1000) + 3600, ...payload })}.sig`;
+}
+
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+describe('native agency authority', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+  let oxy: OxyServices;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    oxy.httpService.setTokens(makeJwt({ userId: 'owner' }));
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  it('loads account-scoped grants and audit events', async () => {
+    fetchMock
+      .mockResolvedValueOnce(jsonResponse({ grants: [] }))
+      .mockResolvedValueOnce(jsonResponse({ events: [] }));
+
+    await expect(oxy.listDelegationGrants('owner/account')).resolves.toEqual([]);
+    await expect(oxy.listCapabilityAuditEvents('owner/account')).resolves.toEqual([]);
+
+    expect(String(fetchMock.mock.calls[0]?.[0])).toBe(
+      'http://test.invalid/capabilities/grants?ownerAccountId=owner%2Faccount',
+    );
+    expect(String(fetchMock.mock.calls[1]?.[0])).toBe(
+      'http://test.invalid/capabilities/audit?accountId=owner%2Faccount',
+    );
+  });
+
+  it('invalidates the exact grant list after revocation', async () => {
+    const clear = jest.spyOn(oxy, 'clearCacheEntry');
+    fetchMock.mockResolvedValueOnce(jsonResponse(undefined));
+
+    await oxy.revokeDelegationGrant('grant/id', 'owner/account');
+
+    expect(String(fetchMock.mock.calls[0]?.[0])).toBe(
+      'http://test.invalid/capabilities/grants/grant%2Fid',
+    );
+    expect(fetchMock.mock.calls[0]?.[1]?.method).toBe('DELETE');
+    expect(clear).toHaveBeenCalledWith(
+      'GET:/capabilities/grants?ownerAccountId=owner%2Faccount',
+    );
+  });
+
+  it('updates only a grant authority envelope through its stable id', async () => {
+    const grant = { id: 'grant/id', catalog: null };
+    fetchMock.mockResolvedValueOnce(jsonResponse({ grant }));
+
+    await expect(oxy.updateDelegationGrant('grant/id', 'owner/account', {
+      capabilityPackages: ['read'],
+      capabilities: ['email.read'],
+      toolOverrides: [{ tool: 'sendEmail', decision: 'deny' }],
+      limits: [],
+      maximumAutonomy: 'read_only',
+      canRedelegate: false,
+      expiresAt: null,
+    })).resolves.toEqual(grant);
+
+    const [url, init] = fetchMock.mock.calls[0] ?? [];
+    expect(String(url)).toBe('http://test.invalid/capabilities/grants/grant%2Fid');
+    expect(init?.method).toBe('PUT');
+    expect(JSON.parse(String(init?.body))).toEqual({
+      capabilityPackages: ['read'],
+      capabilities: ['email.read'],
+      toolOverrides: [{ tool: 'sendEmail', decision: 'deny' }],
+      limits: [],
+      maximumAutonomy: 'read_only',
+      canRedelegate: false,
+      expiresAt: null,
+    });
+  });
+
+  it('writes the most restrictive account policy without leaking it across accounts', async () => {
+    const policy = {
+      id: 'policy-1',
+      accountId: 'account-a',
+      appSlug: 'mention',
+      maximumAutonomy: 'draft' as const,
+      deniedCapabilities: ['social.publish'],
+      createdAt: '2026-09-03T00:00:00.000Z',
+      updatedAt: '2026-09-03T00:00:00.000Z',
+    };
+    fetchMock.mockResolvedValueOnce(jsonResponse({ policy }));
+
+    await expect(oxy.putAccountCapabilityPolicy('mention', {
+      accountId: 'account-a',
+      maximumAutonomy: 'draft',
+      deniedCapabilities: ['social.publish'],
+    })).resolves.toEqual(policy);
+
+    const [url, init] = fetchMock.mock.calls[0] ?? [];
+    expect(String(url)).toBe('http://test.invalid/capabilities/account-policies/mention');
+    expect(init?.method).toBe('PUT');
+    expect(init?.body).toBe(JSON.stringify({
+      accountId: 'account-a',
+      maximumAutonomy: 'draft',
+      deniedCapabilities: ['social.publish'],
+    }));
+  });
+});

package/src/mixins/__tests__/connectedApps.test.ts

@@ -120,4 +120,27 @@ describe('connected apps (OAuth grants)', () => {
     expect(clearSpy).toHaveBeenCalledWith('GET:/auth/grants');
     clearSpy.mockRestore();
   });
+
+  it('lists and revokes resource-bound external MCP clients', async () => {
+    const grant = {
+      id: 'mcp-grant',
+      appSlug: 'noted',
+      resource: 'https://mcp.noted.oxy.so',
+      scopes: ['notes.read'],
+      clientId: 'client-public-id',
+      clientName: 'Research client',
+      createdAt: '2026-09-03T00:00:00.000Z',
+      lastUsedAt: '2026-09-03T01:00:00.000Z',
+    };
+    fetchMock
+      .mockResolvedValueOnce(jsonResponse({ grants: [grant] }))
+      .mockResolvedValueOnce(jsonResponse(undefined));
+
+    await expect(oxy.listConnectedMcpClients()).resolves.toEqual([grant]);
+    await expect(oxy.revokeConnectedMcpClient('mcp/grant')).resolves.toBeUndefined();
+
+    expect(String(fetchMock.mock.calls[0]?.[0])).toBe('http://test.invalid/auth/mcp/oauth/grants');
+    expect(String(fetchMock.mock.calls[1]?.[0])).toBe('http://test.invalid/auth/mcp/oauth/grants/mcp%2Fgrant');
+    expect(fetchMock.mock.calls[1]?.[1]?.method).toBe('DELETE');
+  });
 });

package/src/mixins/index.ts

@@ -17,6 +17,7 @@ import { OxyServicesReputationMixin } from './OxyServices.reputation';
 import { OxyServicesAssetsMixin } from './OxyServices.assets';
 import { OxyServicesAccountsMixin } from './OxyServices.accounts';
 import { OxyServicesConnectedAppsMixin } from './OxyServices.connectedApps';
+import { OxyServicesAgencyMixin } from './OxyServices.agency';
 import { OxyServicesStoreMixin } from './OxyServices.store';
 import { OxyServicesLocationMixin } from './OxyServices.location';
 import { OxyServicesAnalyticsMixin } from './OxyServices.analytics';
@@ -31,7 +32,6 @@ import { OxyServicesAppDataMixin } from './OxyServices.appData';
 import { OxyServicesCivicMixin } from './OxyServices.civic';
 import { OxyServicesChainsMixin } from './OxyServices.chains';
 import { OxyServicesNodesMixin } from './OxyServices.nodes';
-import { OxyServicesLinksMixin } from './OxyServices.links';
 import { OxyServicesFollowGraphMixin } from './OxyServices.followGraph';
 import { OxyServicesInferenceMixin } from './OxyServices.inference';
 import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot';
@@ -58,6 +58,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesAgencyMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesStoreMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>>
@@ -71,7 +72,6 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesChainsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>>
-  & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesFollowGraphMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesInferenceMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>>
@@ -129,6 +129,8 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     // OAuth-consent surface (public app identity + connected-app grants). Kept
     // separate from account ownership.
     OxyServicesConnectedAppsMixin,
+    // Oxy-owned delegated authority for Alia and digital-agent accounts.
+    OxyServicesAgencyMixin,
     // The app store: the public storefront, the reviews on it, and the listing a
     // publisher edits. A module OVER the platform — turn it off and OAuth still
     // works — so it is its own surface rather than more of `accounts`.
@@ -151,9 +153,6 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     // User nodes / decentralization (Fase 5): register/read/revoke/manage the
     // caller's personal data node + ingest hint.
     OxyServicesNodesMixin,
-    // Link previews / unfurls: SDK-owned link-metadata resolution via oxy-api,
-    // so apps stop scraping link metadata locally.
-    OxyServicesLinksMixin,
     // The user-owned follow graph (#809). One relationship per user and target,
     // shared across applications, with per-application context on top.
     OxyServicesFollowGraphMixin,

package/src/models/interfaces.ts

@@ -596,6 +596,33 @@ export interface AssetUpdateVisibilityResponse {
  * deleted ids are omitted from the response (never error the whole batch),
  * so the result may be shorter than the requested id list.
  */
+/**
+ * A short-lived direct download URL for a file the calling application's own
+ * user attached to it, from `POST /assets/service/linked-url`.
+ *
+ * `url` is BEARER AUTHORITY over the bytes for `expiresIn` seconds: whoever
+ * holds the string is the reader, and nothing about the calling service's
+ * entitlement is re-evaluated when it is used. Hand it only to a caller the
+ * service has itself authorized, and never log it.
+ *
+ * `expiresIn` bounds when a transfer may START, not how long one may take. A
+ * large file downloads fine on a slow link; a RESUMED range request after the
+ * deadline does not, and needs a fresh URL.
+ *
+ * Unlike {@link ServiceAssetMetadata}, the absence of an id from the response is
+ * an AUTHORIZATION answer as often as an existence one — see
+ * `getServiceLinkedDownloadUrls`.
+ */
+export interface ServiceLinkedDownloadUrl {
+  id: string;
+  url: string;
+  /** Seconds from issue until `url` stops being accepted. */
+  expiresIn: number;
+  mime: string;
+  size: number;
+  sha256: string;
+}
+
 export interface ServiceAssetMetadata {
   id: string;
   sha256: string;

package/src/server/__tests__/traffic.test.ts

@@ -0,0 +1,49 @@
+import { createEcosystemTraffic } from '../traffic';
+
+jest.mock('../../OxyServices', () => ({ OxyServices: jest.fn(() => ({})) }));
+
+it('publishes independently of viewers and waits for registration before removing a stopped instance', async () => {
+  const originalFetch = globalThis.fetch;
+  const bodies: Array<Record<string, unknown> | unknown[]> = [];
+  let releaseRegistration!: () => void;
+  const registration = new Promise<void>(resolve => { releaseRegistration = resolve; });
+  let registered!: () => void;
+  const registrationStarted = new Promise<void>(resolve => { registered = resolve; });
+  globalThis.fetch = jest.fn(async (_input, init) => {
+    const body = JSON.parse(String(init?.body));
+    bodies.push(body);
+    if (!Array.isArray(body) && !body.removed) {
+      registered();
+      await registration;
+    }
+    return new Response(null, { status: 204 });
+  }) as unknown as typeof fetch;
+  const traffic = createEcosystemTraffic({ service: 'mention', region: 'us-west-2', credential: async () => 'test-service-token', ready: () => true });
+  try {
+    await registrationStarted;
+    traffic.record({ scope: 'internal', direction: 'outbound', activityType: 'communication', sourceRegion: 'us-west-2', targetRegion: 'us-west-2', targetService: 'oxy-api' });
+    const stopped = traffic.stop();
+    expect(bodies.some(body => !Array.isArray(body) && body.removed === true)).toBe(false);
+    releaseRegistration();
+    await stopped;
+    expect(bodies[bodies.length - 1]).toMatchObject({ removed: true, service: 'mention', status: 'online' });
+    expect(bodies.find(Array.isArray)).toEqual([expect.objectContaining({ service: 'mention', scope: 'internal', direction: 'outbound', requests: 1 })]);
+  } finally {
+    releaseRegistration();
+    await traffic.stop();
+    globalThis.fetch = originalFetch;
+  }
+});
+
+it('rejects a partial activity credential instead of mixing it with service credentials', () => {
+  const previous = { ...process.env };
+  try {
+    process.env.OXY_ACTIVITY_API_KEY = 'activity-key';
+    delete process.env.OXY_ACTIVITY_API_SECRET;
+    process.env.OXY_SERVICE_API_KEY = 'service-key';
+    process.env.OXY_SERVICE_API_SECRET = 'service-secret';
+    expect(() => createEcosystemTraffic({ service: 'homiio', region: 'us-west-2' })).toThrow('complete OXY_ACTIVITY');
+  } finally {
+    process.env = previous;
+  }
+});

package/src/server/__tests__/trafficNodeHttp.test.ts

@@ -0,0 +1,38 @@
+import http from 'node:http';
+import { once } from 'node:events';
+import { observeNodeHttp, withoutNodeHttpObservation } from '../trafficNodeHttp';
+import type { TrafficFlow } from '@oxy.so/telemetry/collector';
+
+it('observes real HTTP clients, preserves behavior and restores the HTTP facade', async () => {
+  const events: TrafficFlow[] = [];
+  const original = http.request;
+  const server = http.createServer((_req, res) => { res.setHeader('X-Oxy-Region', 'eu-west-1'); res.end('ok'); });
+  server.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+  const port = (server.address() as { port: number }).port;
+  const stop = observeNodeHttp({ record: flow => events.push(flow) }, 'website', 'us-west-2', () => ({ service: 'oxy-api', region: 'unknown' }));
+  const request = (path: string) => new Promise<void>((resolve, reject) => {
+    const outgoing = http.get(`http://127.0.0.1:${port}${path}`, response => { response.resume(); response.on('end', resolve); });
+    // The observer must not swallow an unhandled request error.
+    expect(outgoing.listenerCount('error')).toBe(0);
+    outgoing.once('error', reject);
+  });
+  try {
+    // Bun leaves Host implicit: its ClientRequest.host is the available authority.
+    const getHeader = http.ClientRequest.prototype.getHeader;
+    http.ClientRequest.prototype.getHeader = function (name: string) { return name === 'host' ? undefined : getHeader.call(this, name); };
+    try { await request('/files/private-id'); } finally { http.ClientRequest.prototype.getHeader = getHeader; }
+    expect(events).toEqual([
+      expect.objectContaining({ scope: 'internal', direction: 'outbound', activityType: 'media', sourceRegion: 'us-west-2', targetRegion: 'eu-west-1' }),
+      expect.objectContaining({ scope: 'internal', direction: 'inbound', sourceRegion: 'eu-west-1', targetRegion: 'us-west-2' }),
+    ]);
+    expect(JSON.stringify(events)).not.toContain('private-id');
+    await withoutNodeHttpObservation(() => request('/files/no-double-count'));
+    await request('/internal/activity');
+    expect(events).toHaveLength(2);
+    stop();
+    expect(http.request).toBe(original);
+    await request('/files/after-stop');
+    expect(events).toHaveLength(2);
+  } finally { stop(); await new Promise<void>(resolve => server.close(() => resolve())); }
+});

package/src/server/index.ts

@@ -134,3 +134,8 @@ export type { OxyIdentityCacheEvictor } from '../utils/identityCacheSweep';
 // lets `@oxy.so/api` derive `auth.<apex>` without duplicating PSL logic.
 export { registrableApex } from '../utils/registrableApex';
 export { isOfficialWebOrigin } from '../utils/officialOrigins';
+
+export { createEcosystemTraffic } from './traffic';
+export type { EcosystemTrafficOptions } from './traffic';
+
+export { observeNodeHttp, withoutNodeHttpObservation } from './trafficNodeHttp';

package/src/server/traffic.ts

@@ -0,0 +1,116 @@
+import { observeNodeHttp, withoutNodeHttpObservation } from './trafficNodeHttp';
+import { observeTrafficSocket, observeTrafficWebSocket, type TrafficWebSocket, type TrafficSocket } from '@oxy.so/telemetry/socket';
+import { randomUUID } from 'node:crypto';
+import type { RequestHandler } from 'express';
+import { OxyServices } from '../OxyServices';
+import { createTrafficCollector, instrumentTrafficFetch, trafficMiddleware, type TrafficFlow, type ServiceEndpoint, resolveOxyServiceEndpoint, infrastructureLocation } from '@oxy.so/telemetry/collector';
+
+export interface EcosystemTrafficOptions {
+  service: string;
+  region?: string;
+  baseURL?: string;
+  credential?: () => Promise<string>;
+  resolveEndpoint?: (url: URL) => ServiceEndpoint | undefined;
+  onError?: () => void;
+  ready?: () => boolean;
+  location?: { label: string; coordinates: [number, number] };
+}
+
+/** Install once per service process, before registering HTTP routes. */
+export function createEcosystemTraffic(options: EcosystemTrafficOptions): {
+  middleware: RequestHandler;
+  record(flow: Omit<TrafficFlow, 'service' | 'region'>): void;
+  wrapFetch(fetcher: typeof fetch): typeof fetch;
+  installFetch(): void;
+  observeHttp: ReturnType<typeof trafficMiddleware>;
+  observeSocket(socket: TrafficSocket, options?: Parameters<typeof observeTrafficSocket>[4]): () => void;
+  observeWebSocket(socket: TrafficWebSocket, options?: Parameters<typeof observeTrafficWebSocket>[4]): () => void;
+  stop(): Promise<void>;
+} {
+  const region = options.region ?? process.env.AWS_REGION ?? 'unknown';
+  const baseURL = options.baseURL ?? process.env.OXY_API_URL ?? 'https://api.oxy.so';
+  const activityKey = process.env.OXY_ACTIVITY_API_KEY;
+  const activitySecret = process.env.OXY_ACTIVITY_API_SECRET;
+  if (!options.credential && Boolean(activityKey) !== Boolean(activitySecret)) {
+    throw new Error('Ecosystem activity requires a complete OXY_ACTIVITY_API_KEY and OXY_ACTIVITY_API_SECRET pair');
+  }
+  const apiKey = activityKey || process.env.OXY_SERVICE_API_KEY;
+  const apiSecret = activitySecret || process.env.OXY_SERVICE_API_SECRET;
+  if (!options.credential && (!apiKey || !apiSecret)) throw new Error('Ecosystem activity requires OXY_SERVICE_API_KEY and OXY_SERVICE_API_SECRET');
+  const oxy = new OxyServices({ baseURL });
+  if (apiKey && apiSecret) oxy.configureServiceAuth(apiKey, apiSecret);
+  const credential = options.credential ?? (() => oxy.getServiceToken());
+  const fetcher = globalThis.fetch.bind(globalThis);
+  const instanceId = randomUUID();
+  const location = options.location ?? infrastructureLocation(region);
+  if (!location) throw new Error('Ecosystem activity requires a known infrastructure region or explicit location');
+  const post = async (path: string, data: unknown) => {
+    const token = await credential();
+    const response = await fetcher(new URL(path, baseURL), {
+      method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+      body: JSON.stringify(data), signal: AbortSignal.timeout(4_000),
+    });
+    if (!response.ok) throw new Error('Activity collection failed');
+  };
+  const collector = createTrafficCollector(events => post('/internal/activity', events));
+  let stopped = false;
+  let heartbeatWork = Promise.resolve();
+  let heartbeatPending = false;
+  const reportError = options.onError ?? (() => console.warn('Ecosystem activity publisher unavailable'));
+  const heartbeat = (removed = false) => {
+    if (!removed && (stopped || heartbeatPending)) return heartbeatWork;
+    heartbeatPending = true;
+    heartbeatWork = heartbeatWork.then(() => post('/internal/activity/infrastructure', { instanceId, service: options.service, region, ...location, status: options.ready?.() ? 'online' : 'unknown', removed })).catch(reportError).finally(() => { heartbeatPending = false; });
+    return heartbeatWork;
+  };
+  const flush = () => collector.flush().catch(reportError);
+  const cleanups = new Set<() => void>();
+  const sockets = new WeakMap<object, () => void>();
+  let fetchInstalled = false;
+  const wrapFetch = (fetcher: typeof fetch): typeof fetch => {
+    const wrapped = instrumentTrafficFetch(fetcher, collector, options.service, region, options.resolveEndpoint ?? resolveOxyServiceEndpoint);
+    return Object.assign((...args: Parameters<typeof fetch>) => withoutNodeHttpObservation(() => wrapped(...args)), fetcher) as typeof fetch;
+  };
+  const observeHttp = trafficMiddleware(collector, options.service, region);
+  const timer = setInterval(() => { void flush(); }, 2_000);
+  timer.unref?.();
+  void heartbeat();
+  const heartbeatTimer = setInterval(() => { void heartbeat(); }, 10_000);
+  heartbeatTimer.unref?.();
+  return {
+    record: flow => collector.record({ ...flow, service: options.service, region }),
+    middleware: observeHttp as RequestHandler,
+    observeHttp,
+    wrapFetch,
+    installFetch() {
+      if (fetchInstalled || stopped) return;
+      fetchInstalled = true;
+      const original = globalThis.fetch;
+      const wrapped = wrapFetch(original);
+      globalThis.fetch = wrapped;
+      cleanups.add(() => { if (globalThis.fetch === wrapped) globalThis.fetch = original; });
+      cleanups.add(observeNodeHttp(collector, options.service, region, options.resolveEndpoint ?? resolveOxyServiceEndpoint));
+    },
+    observeWebSocket(socket, socketOptions) {
+      const existing = sockets.get(socket);
+      if (existing) return existing;
+      const unobserve = observeTrafficWebSocket(socket, collector, options.service, region, socketOptions);
+      const cleanup = () => { unobserve(); socket.off('close', cleanup); cleanups.delete(cleanup); sockets.delete(socket); };
+      sockets.set(socket, cleanup);
+      socket.once('close', cleanup);
+      cleanups.add(cleanup);
+      return cleanup;
+    },
+    observeSocket(socket, socketOptions) {
+      const existing = sockets.get(socket);
+      if (existing) return existing;
+      const unobserve = observeTrafficSocket(socket, collector, options.service, region, socketOptions);
+      const cleanup = () => { unobserve(); socket.off('disconnect', cleanup); cleanups.delete(cleanup); sockets.delete(socket); };
+      sockets.set(socket, cleanup);
+      socket.once('disconnect', cleanup);
+      cleanups.add(cleanup);
+      return cleanup;
+    },
+    async stop() { if (stopped) return; stopped = true; cleanups.forEach(cleanup => cleanup()); cleanups.clear(); clearInterval(timer); clearInterval(heartbeatTimer); await flush(); await heartbeat(true); },
+  };
+}

package/src/server/trafficNodeHttp.ts

@@ -0,0 +1,69 @@
+import http from 'node:http';
+import https from 'node:https';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { syncBuiltinESMExports } from 'node:module';
+import { normalizeInfrastructureRegion, trafficType, type TrafficFlow, type ServiceEndpoint } from '@oxy.so/telemetry/collector';
+
+const suppressed = new AsyncLocalStorage<boolean>();
+export function withoutNodeHttpObservation<T>(callback: () => T): T { return suppressed.run(true, callback); }
+
+/** Node and Bun share the HTTP facade; Bun does not emit Node's HTTP diagnostic channels. */
+export function observeNodeHttp(
+  collector: { record(flow: TrafficFlow): void }, service: string, region: string,
+  resolveEndpoint: (url: URL) => ServiceEndpoint | undefined,
+): () => void {
+  const seen = new WeakSet<http.ClientRequest>();
+  const restoreRequests = new Set<() => void>();
+  const observe = (request: http.ClientRequest) => {
+    if (seen.has(request) || suppressed.getStore()) return request;
+    seen.add(request);
+    const host = request.getHeader('host') ?? request.host;
+    if (typeof host !== 'string') return request;
+    const url = new URL(request.path || '/', `${request.protocol || 'http:'}//${host}`);
+    if (/^\/(?:internal\/activity|auth\/service-token|platform-infrastructure)(?:\/|$)/.test(url.pathname)) return request;
+    const peer = resolveEndpoint(url);
+    if (peer && !request.headersSent) request.setHeader('X-Oxy-Source-Region', region);
+    const flow: TrafficFlow = { service, region, activityType: trafficType(url.pathname), scope: peer ? 'internal' : 'external', direction: 'outbound', sourceRegion: region, sourceService: service, targetService: peer?.service };
+    const emit = request.emit;
+    let recorded = false;
+    const restore = () => { if (request.emit === observedEmit) request.emit = emit; restoreRequests.delete(restore); };
+    // Intercept notifications without adding an 'error' listener: observation
+    // must not turn an unhandled application error into a swallowed error.
+    const observedEmit: typeof request.emit = function (this: http.ClientRequest, event: string | symbol, ...args: unknown[]) {
+      try {
+        if (!recorded && event === 'response') {
+          recorded = true;
+          const response = args[0] as http.IncomingMessage;
+          const targetRegion = peer ? normalizeInfrastructureRegion(response.headers['x-oxy-region']) : undefined;
+          collector.record({ ...flow, targetRegion });
+          collector.record({ ...flow, direction: 'inbound', sourceRegion: targetRegion, targetRegion: region, sourceService: peer?.service, targetService: service });
+        } else if (!recorded && (event === 'error' || event === 'close')) {
+          recorded = true;
+          collector.record(flow);
+        }
+      } catch { /* A metrics failure cannot change a request's behavior. */ }
+      if (event === 'close') restore();
+      return emit.call(this, event, ...args);
+    };
+    request.emit = observedEmit;
+    restoreRequests.add(restore);
+    return request;
+  };
+  const safelyObserve = (request: http.ClientRequest) => {
+    try { return observe(request); } catch { return request; }
+  };
+  const patches = [http, https].map(module => {
+    const request = module.request;
+    const get = module.get;
+    const wrappedRequest = function (...args: Parameters<typeof request>) { return safelyObserve(request.apply(module, args)); } as typeof request;
+    const wrappedGet = function (...args: Parameters<typeof get>) { return safelyObserve(get.apply(module, args)); } as typeof get;
+    module.request = wrappedRequest;
+    module.get = wrappedGet;
+    return () => {
+      if (module.request === wrappedRequest) module.request = request;
+      if (module.get === wrappedGet) module.get = get;
+    };
+  });
+  syncBuiltinESMExports();
+  return () => { patches.forEach(restore => restore()); restoreRequests.forEach(restore => restore()); syncBuiltinESMExports(); };
+}