@moretea-labs/forge 1.8.0 → 1.8.1

package/packages/kernel/identity/domain/grant.ts

@@ -0,0 +1,72 @@
+import type { ScopeRef } from './scope';
+
+export type GrantRiskCeiling = 'readonly' | 'workspace_write' | 'remote_write' | 'destructive';
+
+export interface GrantTarget {
+  kind: string;
+  id: string;
+  repoId?: string;
+  scopeRef?: ScopeRef;
+  identityFingerprint?: string;
+}
+
+export interface Grant {
+  schemaVersion: 1;
+  grantId: string;
+  principalId: string;
+  ownerScope?: string;
+  capabilities: string[];
+  target?: GrantTarget;
+  scopes?: string[];
+  riskCeiling?: GrantRiskCeiling;
+  constraints?: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+  expiresAt: string;
+  revokedAt?: string;
+  revokedReason?: string;
+}
+
+export interface RecordGrantInput {
+  grantId?: string;
+  principalId: string;
+  ownerScope?: string;
+  capabilities: string[];
+  target?: GrantTarget;
+  scopes?: string[];
+  riskCeiling?: GrantRiskCeiling;
+  constraints?: Record<string, unknown>;
+  expiresInMinutes?: number;
+  now?: Date;
+}
+
+export interface RevokeGrantInput {
+  grantId: string;
+  ownerScope?: string;
+  reason: string;
+  now?: Date;
+}
+
+export interface ReconcileGrantsInput {
+  retiredOwnerScopes?: readonly string[];
+  now?: Date;
+}
+
+export interface ReconcileGrantsResult {
+  removedRetiredOwner: number;
+  removedRevoked: number;
+  removedExpired: number;
+  removedTotal: number;
+  remaining: number;
+  changed: boolean;
+}
+
+export interface QueryGrantInput {
+  principalId?: string;
+  ownerScope?: string;
+  capability: string;
+  target?: GrantTarget;
+  scopes?: readonly string[];
+  risk?: 'readonly' | 'workspace_write' | 'remote_write' | 'destructive';
+  at?: Date;
+}

package/packages/kernel/identity/domain/owned-resource.ts

@@ -0,0 +1,116 @@
+/**
+ * Canonical OwnedResource model.
+ * 
+ * Forge-created resources that must survive, recover, or clean up after a crash
+ * carry explicit ownership sufficient to distinguish pre-existing user resources
+ * from Forge-owned worktrees, apps, browser tabs, temporary files/directories,
+ * and provider targets.
+ * 
+ * Cleanup is idempotent resource work derived from owned-resource facts,
+ * not a semantic phase.
+ */
+
+export type OwnedResourceKind =
+  | 'worktree'
+  | 'git_branch'
+  | 'browser_tab'
+  | 'browser_context'
+  | 'temp_dir'
+  | 'temp_file'
+  | 'process'
+  | 'provider_target'
+  | 'tunnel';
+
+export type OwnedResourceStatus = 'active' | 'retained' | 'released' | 'failed_cleanup';
+
+export interface OwnedResourceProvenance {
+  creator: string; // e.g. 'forge:worktree-manager', 'forge:browser-pool', 'work:work-123'
+  createdAt: string;
+  associatedWorkId?: string;
+  associatedRequirementId?: string;
+  repoId?: string;
+}
+
+export interface OwnedResourceRetention {
+  intent: 'temporary' | 'retain_on_failure' | 'persistent_until_explicit_release';
+  expiresAt?: string;
+}
+
+/**
+ * Kind-specific locator space. Cleanup must resolve the resource through its
+ * owning target's own semantics instead of reinterpreting a shared string shape:
+ * a Windows path, WSL path, macOS path, Git ref, browser tab id, pid and provider
+ * target are not interchangeable locators.
+ */
+export type OwnedResourceLocatorKind =
+  | 'filesystem_path'
+  | 'git_ref'
+  | 'browser_tab_id'
+  | 'browser_context_id'
+  | 'process_id'
+  | 'provider_target'
+  | 'tunnel_id';
+
+export interface OwnedResourceLocator {
+  kind: OwnedResourceLocatorKind;
+  value: string;
+}
+
+export interface OwnedResource {
+  schemaVersion: 1;
+  resourceId: string;
+  kind: OwnedResourceKind;
+  targetRef: string; // e.g. path, branch name, tab id, pid
+  /** ForgeInstance that created or adopted the resource; cleanup runs on this owner. */
+  ownerForgeInstanceId?: string;
+  /** Kind-specific locator resolved on the owning ForgeInstance. */
+  locator?: OwnedResourceLocator;
+  /** Stable fingerprint of the locator, so a recycled path/id cannot be reclaimed as the same resource. */
+  identityFingerprint?: string;
+  /** Whether Forge owns enough provenance to release this resource. */
+  cleanupCapable?: boolean;
+  provenance: OwnedResourceProvenance;
+  retention: OwnedResourceRetention;
+  status: OwnedResourceStatus;
+  updatedAt: string;
+  cleanupProof?: {
+    cleanedAt: string;
+    cleanedBy: string;
+    receiptRef?: string;
+  };
+}
+
+export interface RecordOwnedResourceInput {
+  resourceId?: string;
+  kind: OwnedResourceKind;
+  targetRef: string;
+  creator: string;
+  ownerForgeInstanceId?: string;
+  locator?: OwnedResourceLocator;
+  identityFingerprint?: string;
+  cleanupCapable?: boolean;
+  associatedWorkId?: string;
+  associatedRequirementId?: string;
+  repoId?: string;
+  retentionIntent?: OwnedResourceRetention['intent'];
+  expiresAt?: string;
+}
+
+const LOCATOR_KIND_BY_RESOURCE: Record<OwnedResourceKind, OwnedResourceLocatorKind> = {
+  worktree: 'filesystem_path',
+  git_branch: 'git_ref',
+  browser_tab: 'browser_tab_id',
+  browser_context: 'browser_context_id',
+  temp_dir: 'filesystem_path',
+  temp_file: 'filesystem_path',
+  process: 'process_id',
+  provider_target: 'provider_target',
+  tunnel: 'tunnel_id',
+};
+
+/** Kind-specific locator for a resource target. Locator kinds are never interchangeable. */
+export function ownedResourceLocator(kind: OwnedResourceKind, targetRef: string): OwnedResourceLocator {
+  const value = targetRef.trim();
+  if (!value) throw new Error('OWNED_RESOURCE_TARGET_REQUIRED');
+  return { kind: LOCATOR_KIND_BY_RESOURCE[kind], value };
+}

package/packages/kernel/identity/domain/user-request.ts

@@ -0,0 +1,93 @@
+export type UserRequestKind = 'user_action_request' | 'user_decision_request';
+
+export type UserActionRequired =
+  | 'login'
+  | 'grant_permission'
+  | 'confirm_destructive'
+  | 'product_decision';
+
+export interface UserRequestTargetScope {
+  scopeKind: string;
+  scopeId: string;
+  repoId?: string;
+  workId?: string;
+  requirementId?: string;
+}
+
+export interface UserRequestOption {
+  id: string;
+  label: string;
+  description?: string;
+}
+
+export interface UserRequestPresentation {
+  /** Compatibility lookup key for legacy Handoff callers; never a second authority. */
+  legacyHandoffId?: string;
+  severity?: 'info' | 'needs_review' | 'blocked' | 'failed' | 'ready_to_continue';
+  creationReason?: string;
+  reason?: string;
+  currentState?: Record<string, unknown>;
+  attemptedActions?: string[];
+  evidenceRefs?: Array<{ title: string; summary?: string; detailLevel?: 'summary' | 'detail' | 'raw' }>;
+  blockingDecision?: string;
+  recommendedDecision?: string;
+  recommendedPrompt?: string;
+  recommendedContinuationPrompt?: string;
+  approvalAction?: {
+    operation: 'start' | 'repair';
+    label: string;
+    summary: string;
+    risk: string;
+    payload: Record<string, unknown>;
+  };
+  suggestedNextActions?: Array<{
+    label: string;
+    tool?: string;
+    operation?: string;
+    payload?: Record<string, unknown>;
+    risk?: string;
+    confidence?: string;
+    reason?: string;
+  }>;
+}
+
+export interface UserRequest {
+  schemaVersion: 1;
+  requestId: string;
+  kind: UserRequestKind;
+  rootCauseKey: string;
+  title: string;
+  summary: string;
+  actionRequired: UserActionRequired;
+  targetScope?: UserRequestTargetScope;
+  options?: UserRequestOption[];
+  presentation?: UserRequestPresentation;
+  status: 'pending' | 'resolved' | 'cancelled';
+  resolution?: {
+    decision: string;
+    resolvedBy: string;
+    resolvedAt: string;
+  };
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreateUserRequestInput {
+  requestId?: string;
+  kind: UserRequestKind;
+  rootCauseKey: string;
+  title: string;
+  summary: string;
+  actionRequired: UserActionRequired;
+  targetScope?: UserRequestTargetScope;
+  options?: UserRequestOption[];
+  presentation?: UserRequestPresentation;
+  now?: Date;
+}
+
+export interface ResolveUserRequestInput {
+  requestId: string;
+  decision: string;
+  resolvedBy: string;
+  now?: Date;
+}

package/packages/kernel/identity/infrastructure/activity-projection-store.ts

@@ -0,0 +1,77 @@
+import { randomUUID } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, readdirSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import type { CapabilityActivityItem, UnifiedActivityView, WorkTreeProjectionNode } from '../domain/activity-projection';
+
+function activityDir(controllerHome: string): string {
+  const dir = resolve(controllerHome, 'activity-projection');
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+function activityFilePath(controllerHome: string, activityId: string): string {
+  const sanitized = activityId.replace(/[^a-zA-Z0-9._-]/g, '_');
+  return join(activityDir(controllerHome), `${sanitized}.json`);
+}
+
+export function recordDirectActivity(
+  controllerHome: string,
+  input: Omit<CapabilityActivityItem, 'activityId' | 'startedAt'> & { activityId?: string; startedAt?: string },
+): CapabilityActivityItem {
+  const now = new Date().toISOString();
+  const activityId = input.activityId || `act-${randomUUID()}`;
+  const item: CapabilityActivityItem = {
+    ...input,
+    activityId,
+    startedAt: input.startedAt ?? now,
+  };
+
+  const filePath = activityFilePath(controllerHome, activityId);
+  const tmpPath = `${filePath}.${randomUUID()}.tmp`;
+  writeFileSync(tmpPath, JSON.stringify(item, null, 2), 'utf8');
+  renameSync(tmpPath, filePath);
+
+  return item;
+}
+
+export function listDirectActivities(controllerHome: string, limit = 50): CapabilityActivityItem[] {
+  const dir = activityDir(controllerHome);
+  const files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+  const items: CapabilityActivityItem[] = [];
+
+  for (const file of files) {
+    try {
+      const content = readFileSync(join(dir, file), 'utf8');
+      items.push(JSON.parse(content) as CapabilityActivityItem);
+    } catch {
+      // ignore corrupted file
+    }
+  }
+
+  return items
+    .sort((a, b) => b.startedAt.localeCompare(a.startedAt))
+    .slice(0, limit);
+}
+
+/**
+ * Project unified activity view combining WorkTree with direct capability activities.
+ * Direct capability activity that has no Work appears in directActivities rather than
+ * being forced into synthetic Work.
+ */
+export function projectUnifiedActivityView(
+  controllerHome: string,
+  workTreeNodes: WorkTreeProjectionNode[],
+  limitDirect = 50,
+): UnifiedActivityView {
+  const directActivities = listDirectActivities(controllerHome, limitDirect);
+  const now = new Date();
+
+  return {
+    workTree: workTreeNodes,
+    directActivities: directActivities.filter((act) => !act.associatedWorkId),
+    observedAt: now.toISOString(),
+    freshnessMs: 0,
+  };
+}

package/packages/kernel/identity/infrastructure/capability-broker.ts

@@ -0,0 +1,81 @@
+import { randomUUID } from 'crypto';
+import type {
+  CapabilityInvocationInput,
+  CapabilityInvocationResult,
+  CapabilityTypedHandle,
+} from '../domain/capability-broker';
+import { findActiveCanonicalGrant } from './grant-store';
+
+type CapabilityHandler<TArgs = any, TResult = any> = (
+  input: CapabilityInvocationInput<TArgs>,
+) => Promise<CapabilityInvocationResult<TResult>> | CapabilityInvocationResult<TResult>;
+
+class CapabilityRegistry {
+  private handlers = new Map<string, CapabilityHandler>();
+
+  register<TArgs = any, TResult = any>(capabilityId: string, handler: CapabilityHandler<TArgs, TResult>): void {
+    this.handlers.set(capabilityId, handler);
+  }
+
+  get(capabilityId: string): CapabilityHandler | undefined {
+    return this.handlers.get(capabilityId);
+  }
+
+  has(capabilityId: string): boolean {
+    return this.handlers.has(capabilityId);
+  }
+}
+
+export const canonicalCapabilityRegistry = new CapabilityRegistry();
+
+/**
+ * Broker invocation: verifies canonical grant authorization (if required),
+ * validates invocation parameters, and dispatches mechanically without
+ * inferring engineering method or forcing Plan/Work lifecycle.
+ */
+export async function invokeCapability<TArgs = any, TResult = any>(
+  controllerHome: string,
+  input: CapabilityInvocationInput<TArgs>,
+  options: { checkAuthorization?: boolean } = { checkAuthorization: true },
+): Promise<CapabilityInvocationResult<TResult>> {
+  if (options.checkAuthorization) {
+    const grant = findActiveCanonicalGrant(controllerHome, {
+      principalId: input.principalId,
+      capability: input.capabilityId,
+      risk: 'readonly', // base check; fine-grained capability implementations check specific risk
+    });
+    // In local non-interactive automation mode, allow if principal is system/controller or grant exists
+    if (!grant && !['system', 'controller', 'chatgpt-controller', 'claude-controller', 'codex-controller'].includes(input.principalId)) {
+      return {
+        success: false,
+        error: {
+          code: 'UNAUTHORIZED_CAPABILITY',
+          message: `Principal ${input.principalId} lacks active grant for capability ${input.capabilityId}`,
+        },
+      };
+    }
+  }
+
+  const handler = canonicalCapabilityRegistry.get(input.capabilityId);
+  if (!handler) {
+    return {
+      success: false,
+      error: {
+        code: 'CAPABILITY_NOT_FOUND',
+        message: `Capability ${input.capabilityId} is not registered in the broker`,
+      },
+    };
+  }
+
+  try {
+    return await handler(input);
+  } catch (error) {
+    return {
+      success: false,
+      error: {
+        code: 'CAPABILITY_EXECUTION_ERROR',
+        message: error instanceof Error ? error.message : String(error),
+      },
+    };
+  }
+}