borgmcp-shared 0.5.1 → 0.6.1

package/src/protocol/contract.ts

@@ -1,19 +1,32 @@
 import { ErrorCode } from './errors.js';
 import { PROTOCOL_VERSION, type ProtocolVersion } from './version.js';
+import {
+  RuntimeMetadataValidationError,
+  validateRuntimeMetadata,
+  validateRuntimeMetadataPatch,
+  validateRuntimeMetadataReportState,
+} from '../runtime-metadata.js';
+import type {
+  DroneRuntimeMetadata,
+  DroneRuntimeMetadataPatch,
+} from './types.js';
 
 export const SHARED_PACKAGE_NAME = 'borgmcp-shared' as const;
-export const SHARED_PACKAGE_VERSION = '0.5.1' as const;
+export const SHARED_PACKAGE_VERSION = '0.6.1' as const;
 
 export const HEALTH_PATH = '/healthz' as const;
 export const PROTOCOL_INFO_PATH = '/api/protocol' as const;
 export const ENROLLMENT_EXCHANGE_PATH = '/api/enrollment/exchange' as const;
 export const CUBES_PATH = '/api/cubes' as const;
+export const ATTACH_PATH = '/api/client/attach' as const;
+export const SELF_RUNTIME_METADATA_PATH = '/api/cubes/:cubeId/drones/self/metadata' as const;
 
 export const PROTOCOL_HTTP_CONTRACT = {
   health: { method: 'GET', path: HEALTH_PATH, authenticated: false, success_status: 204, bodyless: true },
   protocol: { method: 'GET', path: PROTOCOL_INFO_PATH, authenticated: false, success_status: 200 },
   enrollment: { method: 'POST', path: ENROLLMENT_EXCHANGE_PATH, authenticated: 'invitation', success_status: 201 },
   cubes: { method: 'POST', path: CUBES_PATH, authenticated: true, success_status: 201 },
+  attach: { method: 'POST', path: ATTACH_PATH, authenticated: true, success_status: 200 },
   drone_reassign: {
     method: 'PATCH',
     path: '/api/cubes/:cubeId/drones/:droneId',
@@ -26,6 +39,12 @@ export const PROTOCOL_HTTP_CONTRACT = {
     authenticated: true,
     success_status: 200,
   },
+  drone_self_metadata: {
+    method: 'PATCH',
+    path: SELF_RUNTIME_METADATA_PATH,
+    authenticated: 'drone-session',
+    success_status: 200,
+  },
   auth_missing_status: 401,
   auth_invalid_status: 401,
   auth_expired_status: 401,
@@ -607,15 +626,86 @@ export function maxLogCursor(a: LogCursor | null, b: LogCursor | null): LogCurso
   return compareLogCursor(a, b) >= 0 ? decodeLogCursor(a) : decodeLogCursor(b);
 }
 
-// ── v3 clean-slate wire types ──────────────────────────────────────────────
+function metadataValidation<T>(fn: () => T): T {
+  try {
+    return fn();
+  } catch (error) {
+    if (error instanceof RuntimeMetadataValidationError) {
+      fail(`${error.field}: ${error.reason}`, [error.field]);
+    }
+    throw error;
+  }
+}
 
-export const ATTACH_PATH = '/api/client/attach' as const;
+/** Decode a complete runtime report. When present on attach, all four keys are required. */
+export function decodeDroneRuntimeMetadata(value: unknown): DroneRuntimeMetadata {
+  return metadataValidation(() => validateRuntimeMetadata(value));
+}
+
+/** Decode an atomic self-heal patch. Omitted means unchanged; null means clear. */
+export function decodeDroneRuntimeMetadataPatch(value: unknown): DroneRuntimeMetadataPatch {
+  return metadataValidation(() => validateRuntimeMetadataPatch(value));
+}
+
+/** Decode the flat runtime state carried by Drone objects in roster and regen responses. */
+export function decodeDroneRuntimeMetadataState(value: unknown): UpdateDroneRuntimeMetadataResponse {
+  const input = record(value);
+  return metadataValidation(() => validateRuntimeMetadataReportState({
+    agent_kind: input.agent_kind,
+    reported_model: input.reported_model,
+    working_repo_name: input.working_repo_name,
+    working_repo_origin: input.working_repo_origin,
+  }, input.runtime_metadata_reported));
+}
+
+/** Decode the nested runtime state carried by the own-seat identity response. */
+export function decodeWhoAmIRuntimeMetadataState(value: unknown): UpdateDroneRuntimeMetadataResponse {
+  const input = record(value);
+  return metadataValidation(() => validateRuntimeMetadataReportState(
+    input.runtime_metadata,
+    input.runtime_metadata_reported,
+  ));
+}
+
+export interface UpdateDroneRuntimeMetadataResponse {
+  runtime_metadata: DroneRuntimeMetadata;
+  runtime_metadata_reported: boolean;
+}
+
+export function decodeUpdateDroneRuntimeMetadataResponse(
+  value: unknown,
+): UpdateDroneRuntimeMetadataResponse {
+  const input = record(value);
+  exactKeys(input, ['runtime_metadata', 'runtime_metadata_reported'], [
+    'runtime_metadata',
+    'runtime_metadata_reported',
+  ]);
+  return metadataValidation(() => validateRuntimeMetadataReportState(
+    input.runtime_metadata,
+    input.runtime_metadata_reported,
+  ));
+}
+
+export function decodeUpdateDroneRuntimeMetadataRequestEnvelope(
+  value: unknown,
+): ProtocolEnvelope<DroneRuntimeMetadataPatch> {
+  return decodeProtocolEnvelope(value, decodeDroneRuntimeMetadataPatch);
+}
+
+export function decodeUpdateDroneRuntimeMetadataResponseEnvelope(
+  value: unknown,
+): ProtocolEnvelope<UpdateDroneRuntimeMetadataResponse> {
+  return decodeProtocolEnvelope(value, decodeUpdateDroneRuntimeMetadataResponse);
+}
+
+// ── v3 clean-slate wire types ──────────────────────────────────────────────
 
 export interface AttachRequest {
   cube_id: string;
   role_id: string;
   session_credential: string;
   prior_drone_id?: string;
+  runtime_metadata?: DroneRuntimeMetadata;
 }
 
 export interface AttachCube {
@@ -635,6 +725,8 @@ export interface AttachRole {
 export interface AttachDrone {
   id: string;
   label: string;
+  runtime_metadata: DroneRuntimeMetadata;
+  runtime_metadata_reported: boolean;
 }
 
 export interface AttachSession {
@@ -682,10 +774,20 @@ function decodeAttachRole(value: unknown, path: readonly (string | number)[]): A
 
 function decodeAttachDrone(value: unknown, path: readonly (string | number)[]): AttachDrone {
   const input = record(value, path);
-  exactKeys(input, ['id', 'label'], ['id', 'label'], path);
+  exactKeys(
+    input,
+    ['id', 'label', 'runtime_metadata', 'runtime_metadata_reported'],
+    ['id', 'label', 'runtime_metadata', 'runtime_metadata_reported'],
+    path,
+  );
+  const state = metadataValidation(() => validateRuntimeMetadataReportState(
+    input.runtime_metadata,
+    input.runtime_metadata_reported,
+  ));
   return {
     id: decodeUuid(input.id, [...path, 'id']),
     label: boundedString(input.label, 1, 128, [...path, 'label']),
+    ...state,
   };
 }
 
@@ -703,7 +805,7 @@ function decodeAttachSession(value: unknown, path: readonly (string | number)[])
  */
 export function decodeAttachRequest(value: unknown): AttachRequest {
   const input = record(value);
-  exactKeys(input, ['cube_id', 'role_id', 'session_credential', 'prior_drone_id'], [
+  exactKeys(input, ['cube_id', 'role_id', 'session_credential', 'prior_drone_id', 'runtime_metadata'], [
     'cube_id',
     'role_id',
     'session_credential',
@@ -716,6 +818,9 @@ export function decodeAttachRequest(value: unknown): AttachRequest {
   if (input.prior_drone_id !== undefined) {
     result.prior_drone_id = decodeUuid(input.prior_drone_id, ['prior_drone_id']);
   }
+  if (input.runtime_metadata !== undefined) {
+    result.runtime_metadata = decodeDroneRuntimeMetadata(input.runtime_metadata);
+  }
   return result;
 }
 

package/src/protocol/types.ts

@@ -14,6 +14,20 @@ export type WakePathAlertClass =
   | 'systemic-wake-path-deaf'
   | 'independent';
 
+export interface DroneRuntimeMetadata {
+  agent_kind: AgentKind | null;
+  reported_model: string | null;
+  working_repo_name: string | null;
+  working_repo_origin: string | null;
+}
+
+export interface DroneRuntimeMetadataPatch {
+  agent_kind?: AgentKind | null;
+  reported_model?: string | null;
+  working_repo_name?: string | null;
+  working_repo_origin?: string | null;
+}
+
 export interface Cube {
   id: string;
   owner_id: string;
@@ -45,7 +59,7 @@ export interface Role {
 
 export type PublicRole = Omit<Role, 'detailed_description' | 'detailed_description_hash'>;
 
-export interface Drone {
+export interface Drone extends DroneRuntimeMetadata {
   id: string;
   cube_id: string;
   role_id: string;
@@ -61,10 +75,7 @@ export interface Drone {
   wake_path_client_sse_connected?: boolean | null;
   wake_path_client_monitor_armed?: boolean | null;
   wake_path_alert_class?: WakePathAlertClass | null;
-  agent_kind?: AgentKind | null;
-  reported_model?: string | null;
-  working_repo_name?: string | null;
-  working_repo_origin?: string | null;
+  runtime_metadata_reported: boolean;
   evicted_at?: null;
   created_at: string;
   seen_since?: boolean;
@@ -122,6 +133,8 @@ export interface WhoAmIResponse {
   drone_label: string;
   role_id: string;
   role_name: string;
+  runtime_metadata: DroneRuntimeMetadata;
+  runtime_metadata_reported: boolean;
 }
 
 export interface RosterResponse {

package/src/runtime-metadata.ts

@@ -0,0 +1,304 @@
+import type {
+  DroneRuntimeMetadata,
+  DroneRuntimeMetadataPatch,
+} from './protocol/types.js';
+
+export const RUNTIME_METADATA_LIMITS = {
+  reported_model_bytes: 160,
+  repo_segment_bytes: 100,
+  repo_name_bytes: 201,
+  repo_origin_bytes: 512,
+} as const;
+
+export type RuntimeMetadataField =
+  | 'runtime_metadata'
+  | 'runtime_metadata_reported'
+  | 'agent_kind'
+  | 'reported_model'
+  | 'working_repo_name'
+  | 'working_repo_origin';
+
+export class RuntimeMetadataValidationError extends Error {
+  constructor(
+    public readonly field: RuntimeMetadataField,
+    public readonly reason: string,
+  ) {
+    super(`${field}: ${reason}`);
+    this.name = 'RuntimeMetadataValidationError';
+  }
+}
+
+const MODEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._/@:+-]*$/;
+const REPO_SEGMENT_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,98}[A-Za-z0-9])?$/;
+const UNSAFE_UNICODE_PATTERN = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]|\p{Bidi_Control}/u;
+
+function byteLength(value: string): number {
+  let bytes = 0;
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index);
+    if (code <= 0x7f) bytes += 1;
+    else if (code <= 0x7ff) bytes += 2;
+    else if (code >= 0xd800 && code <= 0xdbff) {
+      bytes += 4;
+      index++;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+
+function hasMalformedUnicode(value: string): boolean {
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index);
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (next < 0xdc00 || next > 0xdfff) return true;
+      index++;
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function invalid(field: RuntimeMetadataField, reason: string): never {
+  throw new RuntimeMetadataValidationError(field, reason);
+}
+
+const METADATA_KEYS = [
+  'agent_kind',
+  'reported_model',
+  'working_repo_name',
+  'working_repo_origin',
+] as const;
+
+function metadataRecord(value: unknown): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    invalid('runtime_metadata', 'must be an object');
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    invalid('runtime_metadata', 'must be a plain object');
+  }
+  const keys = Reflect.ownKeys(value);
+  if (keys.some((key) => typeof key !== 'string' || !METADATA_KEYS.includes(key as typeof METADATA_KEYS[number]))) {
+    invalid('runtime_metadata', 'contains an unsupported field');
+  }
+  if (keys.some((key) => {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return descriptor === undefined || !Object.prototype.hasOwnProperty.call(descriptor, 'value');
+  })) {
+    invalid('runtime_metadata', 'fields must be plain data values');
+  }
+  return value as Record<string, unknown>;
+}
+
+function agentKind(value: unknown): DroneRuntimeMetadata['agent_kind'] {
+  if (value === null || value === 'claude' || value === 'codex' || value === 'opencode') {
+    return value;
+  }
+  invalid('agent_kind', 'must be claude, codex, opencode, or null');
+}
+
+function nullableString(value: unknown, field: RuntimeMetadataField): string | null {
+  if (value === null || typeof value === 'string') return value;
+  invalid(field, 'must be a string or null');
+}
+
+export function validateReportedModel(value: string): string {
+  const bytes = byteLength(value);
+  if (bytes < 1 || bytes > RUNTIME_METADATA_LIMITS.reported_model_bytes) {
+    invalid('reported_model', 'must be 1-160 UTF-8 bytes');
+  }
+  if (hasMalformedUnicode(value) || UNSAFE_UNICODE_PATTERN.test(value) || !MODEL_PATTERN.test(value)) {
+    invalid('reported_model', 'must be a printable model identifier');
+  }
+  return value;
+}
+
+export function validateWorkingRepoName(value: string): string {
+  if (byteLength(value) > RUNTIME_METADATA_LIMITS.repo_name_bytes) {
+    invalid('working_repo_name', 'must be at most 201 bytes');
+  }
+  const segments = value.split('/');
+  if (
+    segments.length !== 2 ||
+    segments.some((segment) =>
+      segment === '.' ||
+      segment === '..' ||
+      byteLength(segment) > RUNTIME_METADATA_LIMITS.repo_segment_bytes ||
+      !REPO_SEGMENT_PATTERN.test(segment)
+    )
+  ) {
+    invalid('working_repo_name', 'must be a canonical owner/repository name');
+  }
+  return value;
+}
+
+function validatePublicHost(hostname: string): string {
+  const host = hostname.toLowerCase();
+  if (
+    host.length > 253 ||
+    !host.includes('.') ||
+    host.includes(':') ||
+    /^(?:0x[0-9a-f]+|\d+)(?:\.(?:0x[0-9a-f]+|\d+)){1,3}$/.test(host) ||
+    /(?:^|\.)(?:localhost|local|internal|lan)$/.test(host)
+  ) {
+    invalid('working_repo_origin', 'must use a public DNS host');
+  }
+  const labels = host.split('.');
+  if (labels.some((label) => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label))) {
+    invalid('working_repo_origin', 'must use a public DNS host');
+  }
+  return host;
+}
+
+function originParts(value: string): { host: string; path: string } {
+  if (
+    byteLength(value) > RUNTIME_METADATA_LIMITS.repo_origin_bytes ||
+    value.includes('%') ||
+    hasMalformedUnicode(value) ||
+    UNSAFE_UNICODE_PATTERN.test(value) ||
+    /[\u0080-\uffff]/u.test(value)
+  ) {
+    invalid('working_repo_origin', 'must be a safe canonical repository URL');
+  }
+
+  const scp = /^git@([^/:]+):(.+)$/.exec(value);
+  if (scp) return { host: validatePublicHost(scp[1]), path: scp[2] };
+
+  const hierarchical = /^(https|ssh):\/\/([^/]+)\/(.+)$/.exec(value);
+  if (!hierarchical) {
+    invalid('working_repo_origin', 'must be an HTTPS or Git SSH repository URL');
+  }
+  const [, scheme, authority, path] = hierarchical;
+  if (path.includes('?') || path.includes('#')) {
+    invalid('working_repo_origin', 'must not include a query or fragment');
+  }
+  if (scheme === 'https') {
+    if (authority.includes('@')) {
+      invalid('working_repo_origin', 'must not include credentials or a non-default port');
+    }
+    const hostMatch = /^([^:]+)(?::443)?$/.exec(authority);
+    if (!hostMatch) {
+      invalid('working_repo_origin', 'must not include credentials or a non-default port');
+    }
+    return { host: validatePublicHost(hostMatch[1]), path };
+  }
+  const sshMatch = /^git@([^:]+)(?::22)?$/.exec(authority);
+  if (!sshMatch) {
+      invalid('working_repo_origin', 'SSH repository URLs require the literal git user');
+  }
+  return { host: validatePublicHost(sshMatch[1]), path };
+}
+
+export interface CanonicalRepositoryIdentity {
+  working_repo_name: string;
+  working_repo_origin: string;
+}
+
+export function canonicalizeRepositoryIdentity(
+  inputOrigin: string,
+  expectedName?: string,
+): CanonicalRepositoryIdentity {
+  const { host, path: rawPath } = originParts(inputOrigin);
+  const path = rawPath.endsWith('.git') ? rawPath.slice(0, -4) : rawPath;
+  if (path.includes('\\') || path.startsWith('/') || path.endsWith('/')) {
+    invalid('working_repo_origin', 'must identify exactly one owner/repository path');
+  }
+  const name = validateWorkingRepoName(path);
+  if (expectedName !== undefined && validateWorkingRepoName(expectedName) !== name) {
+    invalid('working_repo_name', 'must match the canonical repository origin');
+  }
+  return {
+    working_repo_name: name,
+    working_repo_origin: `https://${host}/${name}`,
+  };
+}
+
+export function validateRuntimeMetadata(value: unknown): DroneRuntimeMetadata {
+  const input = metadataRecord(value);
+  if (METADATA_KEYS.some((key) => !Object.prototype.hasOwnProperty.call(input, key))) {
+    invalid('runtime_metadata', 'must contain all four metadata fields');
+  }
+  const metadata: DroneRuntimeMetadata = {
+    agent_kind: agentKind(input.agent_kind),
+    reported_model: nullableString(input.reported_model, 'reported_model'),
+    working_repo_name: nullableString(input.working_repo_name, 'working_repo_name'),
+    working_repo_origin: nullableString(input.working_repo_origin, 'working_repo_origin'),
+  };
+  if (metadata.reported_model !== null) validateReportedModel(metadata.reported_model);
+  if ((metadata.working_repo_name === null) !== (metadata.working_repo_origin === null)) {
+    invalid('working_repo_name', 'repository name and origin must be set or cleared together');
+  }
+  if (metadata.working_repo_name !== null && metadata.working_repo_origin !== null) {
+    const canonical = canonicalizeRepositoryIdentity(
+      metadata.working_repo_origin,
+      metadata.working_repo_name,
+    );
+    return { ...metadata, ...canonical };
+  }
+  return { ...metadata };
+}
+
+export function validateRuntimeMetadataPatch(
+  value: unknown,
+): DroneRuntimeMetadataPatch {
+  const input = metadataRecord(value);
+  if (Reflect.ownKeys(input).length === 0) invalid('runtime_metadata', 'patch must not be empty');
+  const patch: DroneRuntimeMetadataPatch = {};
+  if (Object.prototype.hasOwnProperty.call(input, 'agent_kind')) {
+    patch.agent_kind = agentKind(input.agent_kind);
+  }
+  if (Object.prototype.hasOwnProperty.call(input, 'reported_model')) {
+    patch.reported_model = nullableString(input.reported_model, 'reported_model');
+  }
+  if (Object.prototype.hasOwnProperty.call(input, 'working_repo_name')) {
+    patch.working_repo_name = nullableString(input.working_repo_name, 'working_repo_name');
+  }
+  if (Object.prototype.hasOwnProperty.call(input, 'working_repo_origin')) {
+    patch.working_repo_origin = nullableString(input.working_repo_origin, 'working_repo_origin');
+  }
+  if (patch.reported_model !== undefined && patch.reported_model !== null) {
+    validateReportedModel(patch.reported_model);
+  }
+  const hasName = patch.working_repo_name !== undefined;
+  const hasOrigin = patch.working_repo_origin !== undefined;
+  if (hasName !== hasOrigin) {
+    invalid('working_repo_name', 'repository name and origin must be patched together');
+  }
+  if (hasName && hasOrigin) {
+    const name = patch.working_repo_name;
+    const origin = patch.working_repo_origin;
+    if ((name === null) !== (origin === null)) {
+      invalid('working_repo_name', 'repository name and origin must be set or cleared together');
+    }
+    if (name !== null && name !== undefined && origin !== null && origin !== undefined) {
+      const canonical = canonicalizeRepositoryIdentity(
+        origin,
+        name,
+      );
+      return { ...patch, ...canonical };
+    }
+  }
+  return { ...patch };
+}
+
+export interface ValidatedRuntimeMetadataReportState {
+  runtime_metadata: DroneRuntimeMetadata;
+  runtime_metadata_reported: boolean;
+}
+
+/** Enforce the response invariant shared by attach, self-update, and identity reads. */
+export function validateRuntimeMetadataReportState(
+  metadataValue: unknown,
+  reportedValue: unknown,
+): ValidatedRuntimeMetadataReportState {
+  const runtime_metadata = validateRuntimeMetadata(metadataValue);
+  if (typeof reportedValue !== 'boolean') {
+    invalid('runtime_metadata_reported', 'must be a boolean');
+  }
+  if (!reportedValue && Object.values(runtime_metadata).some((value) => value !== null)) {
+    invalid('runtime_metadata_reported', 'false requires all metadata values to be null');
+  }
+  return { runtime_metadata, runtime_metadata_reported: reportedValue };
+}