Feature request: expose headless patch generation through the TypeScript SDK

Summary

Please expose Codex Security patch generation through the public TypeScript SDK.

The SDK currently provides CodexSecurity.run() and CodexSecurity.validate(), while remediation is available through the codex-security patch CLI and the bundled fix-finding skill.

Applications embedding the SDK must launch and supervise a CLI subprocess to generate patches. A supported headless SDK method would enable approval-gated remediation platforms without requiring direct CLI integration.

Use case

An application may:

1. Run a Codex Security scan or import findings from SARIF, GitHub Code Scanning, or another scanner.
2. Let a user select an individual finding.
3. Prepare an isolated repository workspace.
4. Ask Codex Security to generate and verify a patch.
5. Independently derive and hash the resulting diff.
6. Present the immutable patch for human approval.
7. Export it or create a pull request through the application's own delivery controls.

The application should retain responsibility for approval, commit creation, publication, and finding closure.

Suggested API

const security = new CodexSecurity(config);

const result = await security.patch({
  repositoryPath: "/path/to/disposable/workspace",
  finding: {
    title: "Possible SQL injection",
    severity: "high",
    summary: "User input reaches a raw SQL query.",
    locations: [{ path: "src/query.ts", startLine: 42 }],
  },
  assessPatchRisk: true,
  signal,
  onActivity(activity) {
    // Persist or display remediation progress.
  },
  onSessionEvent(event) {
    // Capture task/session lineage.
  },
  onCost(cost) {
    // Display model consumption when available.
  },
});

Possible result contract:

interface PatchResult {
  status: "verified" | "no_change" | "blocked" | "failed";
  changedFiles: string[];
  verificationReport: string;
  patchRiskReport?: string;
  threadId: string | null;
  outputDir?: string;
  usage?: {
    inputTokens?: number;
    cachedInputTokens?: number;
    outputTokens?: number;
    estimatedCostUsd?: number;
  };
  reason?: string;
}

The method may edit only the supplied repository workspace. Returning a patch artifact path or structured changed-file information would also be useful, but callers should remain able to derive the authoritative Git diff themselves.

Requested behavior

• Accept finding text or a JSON-serializable finding object.
• Operate non-interactively.
• Reuse the CodexSecurity constructor configuration.
• Support the same explicit authentication and provider configuration contract as other SDK operations, where technically available.
• Support model and reasoning-effort selection.
• Support AbortSignal.
• Expose activity, session, warning, and cost callbacks.
• Return structured patch and verification status.
• Preserve the existing fix-finding investigation and verification workflow.
• Avoid committing, pushing, opening pull requests, or changing remote finding state.
• Avoid including credentials in arguments, results, logs, or artifacts.
• Clearly document that the supplied workspace may be modified.

Why an SDK method is useful

Invoking the CLI from an SDK-based application requires the caller to manage:

• executable discovery
• child-process lifecycle and cancellation
• stdout/stderr parsing
• authentication environment handling
• provider configuration
• timeout and output limits
• structured status recovery
• version compatibility

The CLI should remain available for interactive and terminal workflows. The requested API would provide the same remediation engine through a stable programmatic contract.

Related work

• PR #461 added CLI finding review, patching, and optional pull requests.
• PR #646 added SDK and CLI import of GitHub Code Scanning alerts.
• The existing CodexSecurity.validate() API demonstrates a similar structured, non-interactive finding workflow.

This request is specifically for patch generation and verification. It does not request automatic approval, merge, publication, or finding closure.

Start by reading the existing CodexSecurity.run() and CodexSecurity.validate() APIs, then trace the codex-security patch CLI and bundled fix-finding workflow. Compare their authentication, provider, model, cancellation, callback, and verification behavior with the requested patch contract. Done means a documented non-interactive SDK method that modifies only the supplied workspace, returns structured status, and preserves approval and publication responsibilities for callers.