fix: improve compatibility with current ChatGPT MCP behavior

agents/design.md

@@ -0,0 +1,15 @@
+---
+schema: devspace-agent/v1
+name: design
+description: Read-only UI and UX audit specialist requiring real rendered evidence.
+provider: codex
+write-mode: read_only
+thinking: high
+---
+
+Audit visual hierarchy, spacing, typography, responsiveness, mobile usability, accessibility,
+contrast, focus/hover/selected states, overflow, and design-system consistency. Use design_audit
+artifacts when available. If real screenshots or rendered evidence are unavailable, report the
+audit as unverified and do not issue a passing judgment.
+
+Return evidence, findings, affected routes/components, and the next validation action.

agents/explore.md

@@ -0,0 +1,22 @@
+---
+schema: devspace-agent/v1
+name: explore
+description: Read-only specialist for structure, root-cause, and impact investigation.
+provider: codex
+write-mode: read_only
+thinking: high
+---
+
+Investigate without editing, staging, committing, pushing, deploying, or changing external state.
+Prefer CodeGraph when available, then focused search and only necessary reads. Do not perform broad scans.
+
+Return:
+
+```text
+rootCause:
+relevantFiles:
+relevantSymbols:
+impactRadius:
+evidence:
+nextAction:
+```

agents/implement.md

@@ -0,0 +1,22 @@
+---
+schema: devspace-agent/v1
+name: implement
+description: Focused implementation specialist for verified, minimal code changes.
+provider: codex
+write-mode: allowed
+thinking: high
+---
+
+Confirm the root cause, then implement the smallest correct change. Preserve unrelated and
+uncommitted work. Do not add dependencies without proof, and do not deploy, push, commit, or
+repeat builds/tests without a specific reason.
+
+Return:
+
+```text
+rootCause:
+changes:
+tests:
+risks:
+remaining:
+```

agents/review.md

@@ -0,0 +1,15 @@
+---
+schema: devspace-agent/v1
+name: review
+description: Read-only diff reviewer for correctness, security, regression, and scope risk.
+provider: codex
+write-mode: read_only
+thinking: high
+---
+
+Review without editing or changing Git state. Inspect correctness, security, type safety,
+performance, regressions, scope creep, dependencies, permission boundaries, secret exposure,
+payload growth, and compact-mode regressions.
+
+Return findings in severity order with evidence, affected files, and a recommended fix.
+Explicitly state when no actionable issue is found.

compatibility-kit/openai-model-compatibility-2026-07/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 2026.07.2
+
+- Added safe standard PATH augmentation without sourcing login-shell files.
+- Added bounded runtime diagnosis and compatibility smoke checks through the
+  existing Bash Tool instead of expanding the model-facing Tool catalog.
+- Expanded usage estimates into execution-cost summaries with observed duration,
+  calls, errors, retries, and character volume.
+- Added workspace-scoped Finder integration as an app-only Tool and result-card
+  action, with root-guard validation.
+- Added dedicated runtime tests and three ordered compatibility patches.
+
+## 2026.07.1
+
+- Added compact `open_workspace` payload behavior with bounded instruction
+  excerpts and explicit full reads.
+- Added exact-path access for advertised instruction files outside the project
+  root without widening directory access.
+- Added optional text-volume diagnostics.
+- Added optional compound inspection tools and safe inspection helpers.
+- Added explicitly configured approved-shell aliases with workspace validation.
+- Added optional built-in agent profiles, skill matching, design-audit tooling,
+  and generic skill templates.
+- Added tests, feature flags, configuration documentation, and updater scripts.
+- Removed private branding, personal paths, private endpoints, configuration
+  values, and local diagnostic artifacts from the public proposal.
+- Documented that the compatibility workflow was prepared through ChatGPT
+  instructions using DevSpace itself.

compatibility-kit/openai-model-compatibility-2026-07/README.md

@@ -0,0 +1,97 @@
+# DevSpace OpenAI Model Compatibility Kit
+
+This directory packages a reviewable compatibility update for DevSpace v1.0.4.
+It was prepared after a recent ChatGPT model rollout changed the practical
+behavior of multi-step MCP tool execution. The observed regression affected both
+GPT-5.5 and GPT-5.6: operations that had previously completed normally became
+slow, stalled, or unreliable.
+
+This is intentionally described as a compatibility update rather than a
+GPT-5.6-only patch. No assumption is made about undocumented OpenAI internals.
+
+## What this kit changes
+
+- Reduces the initial `open_workspace` payload through bounded instruction
+  excerpts and lazy full-file reads.
+- Keeps advertised instruction files readable without widening the workspace
+  filesystem allowlist.
+- Adds execution-cost diagnostics for response volume, duration, Tool calls,
+  errors, and retries while keeping token values explicitly approximate.
+- Adds opt-in compound inspection tools for common, bounded read-only workflows.
+- Adds safer support for explicitly pre-approved shell command aliases.
+- Improves built-in agent profile, skill matching, design-audit, and MCP App
+  integration paths while keeping the features opt-in.
+- Adds safe standard PATH discovery without sourcing login-shell configuration.
+- Integrates runtime diagnosis, compatibility smoke checks, cost snapshots, and
+  workspace-scoped Finder actions into the existing Tool surface.
+- Includes tests for the compatibility behavior and feature flags.
+
+## Scope and privacy
+
+The bundle contains only generic DevSpace changes. It does not contain:
+
+- personal filesystem paths or usernames;
+- private repositories or private integration endpoints;
+- credentials, access tokens, cookies, owner passwords, or private keys;
+- machine-specific allowlists or approved command configurations;
+- custom product names or private branding;
+- personal logs, usage history, or screenshots.
+
+See `docs/SECURITY_AND_PRIVACY.md` for the sanitization rules.
+
+## Requirements
+
+- A clean checkout of `Waishnav/devspace` at release `v1.0.4` or commit
+  `d03187460cebdc2820e797cb59740537100a0f99`.
+- Node.js compatible with the repository's `engines` field.
+- Git available on `PATH`.
+
+## Apply
+
+From the root of a clean DevSpace v1.0.4 checkout:
+
+    node compatibility-kit/openai-model-compatibility-2026-07/apply.mjs
+
+The script performs all `git apply --check` operations before changing files. It
+refuses to run against a dirty working tree or an unsupported package/version.
+
+Then validate:
+
+    node compatibility-kit/openai-model-compatibility-2026-07/verify.mjs
+
+The verification script runs dependency installation, type checking, tests, and
+the production build. Review the diff before committing.
+
+## Roll back
+
+Before applying, create a branch or commit in the target checkout. If the patch
+has not been committed, restore the checkout with Git after reviewing the
+changes. The apply script does not commit, push, publish, deploy, or modify user
+configuration.
+
+## Maintainer review
+
+The patch set is split by responsibility:
+
+1. `0001-compact-workspace-and-usage.patch`
+2. `0002-safe-tools-and-compound-inspection.patch`
+3. `0003-agents-skills-app-integration.patch`
+4. `0004-runtime-diagnostics-and-costs.patch`
+5. `0005-existing-tool-runtime-integration.patch`
+6. `0006-finder-app-action.patch`
+
+The same changes are also present directly in the pull-request branch, so the
+maintainer can review normal source diffs without running the updater.
+
+## Dogfooding note
+
+The investigation, sanitization, compatibility-kit preparation, validation, and
+GitHub delivery workflow were executed from ChatGPT instructions using DevSpace
+itself. This demonstrates the exact MCP workflow being improved; it is not a
+security guarantee or a substitute for maintainer review.
+
+## Status
+
+This is a community compatibility proposal, not an official DevSpace release.
+Feature flags remain opt-in where practical, and upstream maintainers retain
+full control over naming, versioning, scope, and release decisions.

compatibility-kit/openai-model-compatibility-2026-07/apply.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const kitDir = dirname(fileURLToPath(import.meta.url));
+const manifest = JSON.parse(await readFile(resolve(kitDir, "manifest.json"), "utf8"));
+const args = process.argv.slice(2);
+const repoArgIndex = args.indexOf("--repo");
+const repoRoot = resolve(repoArgIndex >= 0 ? args[repoArgIndex + 1] ?? "" : process.cwd());
+const kitRelativePrefix = "compatibility-kit/openai-model-compatibility-2026-07/";
+
+function run(command, commandArgs, options = {}) {
+  const result = spawnSync(command, commandArgs, {
+    cwd: repoRoot,
+    encoding: "utf8",
+    stdio: options.capture ? "pipe" : "inherit",
+  });
+  if (result.error) throw result.error;
+  return result;
+}
+
+function requireSuccess(result, message) {
+  if (result.status !== 0) {
+    const detail = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
+    throw new Error(detail ? `${message}\n${detail}` : message);
+  }
+}
+
+const packagePath = resolve(repoRoot, "package.json");
+let packageJson;
+try {
+  packageJson = JSON.parse(await readFile(packagePath, "utf8"));
+} catch {
+  throw new Error(`Could not read a package.json at ${repoRoot}`);
+}
+
+if (packageJson.name !== manifest.target.package) {
+  throw new Error(`Expected ${manifest.target.package}, found ${packageJson.name ?? "unknown"}.`);
+}
+if (packageJson.version !== manifest.target.version) {
+  throw new Error(
+    `This bundle targets DevSpace ${manifest.target.version}; found ${packageJson.version ?? "unknown"}.`,
+  );
+}
+
+const inside = run("git", ["rev-parse", "--is-inside-work-tree"], { capture: true });
+requireSuccess(inside, "The target directory is not a Git working tree.");
+
+const status = run("git", ["status", "--porcelain=v1"], { capture: true });
+requireSuccess(status, "Could not inspect the target working tree.");
+const blockingChanges = status.stdout
+  .split("\n")
+  .map((line) => line.trimEnd())
+  .filter(Boolean)
+  .filter((line) => !line.slice(3).startsWith(kitRelativePrefix));
+if (blockingChanges.length > 0) {
+  throw new Error(
+    "Refusing to patch a dirty working tree. Commit, stash, or remove existing changes first.",
+  );
+}
+
+for (const patch of manifest.patches) {
+  const patchPath = resolve(kitDir, patch.path);
+  const check = run("git", ["apply", "--check", "--whitespace=error-all", patchPath], {
+    capture: true,
+  });
+  requireSuccess(check, `Patch preflight failed: ${patch.path}`);
+}
+
+const applied = [];
+try {
+  for (const patch of manifest.patches) {
+    const patchPath = resolve(kitDir, patch.path);
+    const apply = run("git", ["apply", "--whitespace=fix", patchPath], { capture: true });
+    requireSuccess(apply, `Could not apply ${patch.path}`);
+    applied.push(patchPath);
+    console.log(`Applied ${patch.path}`);
+  }
+} catch (error) {
+  for (const patchPath of applied.reverse()) {
+    run("git", ["apply", "--reverse", patchPath], { capture: true });
+  }
+  throw error;
+}
+
+console.log("Compatibility patches applied. No commit, push, publish, or deploy was performed.");
+console.log("Run verify.mjs, inspect git diff, and commit only after review.");

compatibility-kit/openai-model-compatibility-2026-07/docs/ARCHITECTURE.md

@@ -0,0 +1,98 @@
+# Architecture and Integration Notes
+
+## Problem statement
+
+After a recent ChatGPT model rollout, multi-step DevSpace sessions became
+materially slower or less reliable with both GPT-5.5 and GPT-5.6. The practical
+failure mode was not limited to one model name: large initial tool payloads and
+verbose repeated tool results increased the amount of context exchanged before
+useful work could begin.
+
+This proposal does not depend on undocumented model internals. It reduces the
+amount of information sent eagerly, makes follow-up reads explicit, and adds
+bounded higher-level operations for common workflows.
+
+## Workspace lifecycle
+
+The MCP client calls `open_workspace` once for a checkout or managed worktree.
+The returned `workspaceId` is then reused for file reads, searches, edits,
+writes, and shell execution.
+
+The compatibility behavior changes the initial response as follows:
+
+- Instruction files are represented by bounded excerpts in compact mode.
+- Full instruction content remains available through the existing `read` tool.
+- Nested instruction paths are advertised without eagerly sending every file.
+- Skill descriptions and diagnostics are omitted from the initial compact
+  payload when they are not needed.
+- Payload and instruction-character metrics are returned for diagnosis.
+
+This preserves the instruction-following contract while reducing initial MCP
+response size.
+
+## Safe instruction reads
+
+An instruction file may live outside the selected project root, for example in
+a user-level agent configuration directory. The workspace registry records only
+instruction paths that were explicitly discovered and advertised during
+workspace opening. A later `read` can access those exact files, but this does not
+create a general read permission for their parent directories.
+
+## Tool result metrics
+
+The usage meter estimates text volume from characters handled by DevSpace. It is
+not OpenAI usage, token billing, or a model-provider measurement. Its purpose is
+to compare payload sizes and identify unnecessary context expansion.
+
+The reporting mode is configurable:
+
+- `off`: do not append estimates to tool results;
+- `compact`: append a one-line estimate;
+- `full`: append per-tool and estimated-savings details.
+
+History writes are diagnostic-only and cannot fail the underlying tool call.
+
+## Compound tools
+
+Optional compound tools combine bounded, commonly repeated read-only steps.
+They reduce round trips without introducing an autonomous execution loop. Each
+compound tool retains explicit input schemas, workspace scoping, output limits,
+and the same path-resolution rules as the primitive tools.
+
+The primitive file and shell tools remain available. Compound tools are disabled
+unless explicitly enabled.
+
+## Approved shell aliases
+
+The approved-command mechanism does not accept an arbitrary command definition
+from the MCP client. The client supplies only an alias. DevSpace resolves that
+alias from a local configuration file and verifies:
+
+- the alias syntax;
+- that the entry is enabled;
+- that its configured workspace root exactly matches the active workspace;
+- that the configured working directory remains within the allowed root;
+- that the locally configured command is non-empty.
+
+The local approved-command file is not included in this compatibility bundle.
+
+## Agents, skills, and Apps
+
+The proposal adds generic built-in agent profiles and skills as optional
+capabilities. It also keeps MCP App metadata and structured tool content aligned
+with compact-mode results. These components are generic templates and contain
+no private integration destinations or user-specific configuration.
+
+Feature flags allow maintainers and users to adopt the capabilities separately:
+
+- `DEVSPACE_SKILL_MATCHER`
+- `DEVSPACE_COMPOUND_TOOLS`
+- `DEVSPACE_BUILTIN_PROFILES`
+- `DEVSPACE_DESIGN_AUDIT`
+
+## Compatibility posture
+
+The branch keeps the upstream package version unchanged. Version selection and
+release publication belong to the upstream maintainer. The compatibility kit
+applies source changes only and never commits, pushes, publishes, deploys, or
+changes user configuration.