ai_context 1.0.0-RC1 Compatibility Reference¶

READ THIS BEFORE any ai_context upgrade or AiContextScope plugin authorship.

RC1 Breaking Changes¶

ai_context 1.0.0-RC1 (released 2026-09-25) introduced two breaking changes to the AiContextScope plugin system that cause PHP Fatal errors on every site unless all consumer plugins are updated.

1. `doGetDetectedValue()` is now abstract¶

AiContextScopeBase added:

abstract protected function doGetDetectedValue(): ?string;

Every plugin that extends AiContextScopeBase must implement this method.

The common stub for scopes with no auto-detectable request signal:

/**
 * {@inheritdoc}
 *
 * No ambient request signal exists to auto-detect a value for this scope.
 * Returns NULL so the scope system correctly treats it as non-detectable.
 */
protected function doGetDetectedValue(): ?string {
  return NULL;
}

2. `weight` parameter removed from `#[AiContextScope]` attribute¶

Before RC1:

#[AiContextScope(
  id: 'my_scope',
  label: new TranslatableMarkup('My Scope'),
  description: new TranslatableMarkup('...'),
  weight: 20,   // ← REMOVED in RC1 — causes Fatal
)]

After RC1:

#[AiContextScope(
  id: 'my_scope',
  label: new TranslatableMarkup('My Scope'),
  description: new TranslatableMarkup('...'),
  // weight removed; use display_weight if needed
)]

Affected Bluefly Packages — Status as of 2026-09-26¶

Package	Canonical repo	Plugins affected	MR	Status
`drupal/ai_agents_ossa`	`contrib-ready/ai_agents_ossa`	`OssaAgentKindScope`	!225	✅ Already RC1-ready in canonical; MR fixes `composer.json` type only
`drupal/ai_agents_agui`	`private/ai_agents_agui`	`AgUiContextScope`	!22	🔄 MR open — adds `doGetDetectedValue()` + fixes type
`drupal/duadp`	`contrib-ready/duadp_client`	`A2aAgentScope`, `DuadpNodeScope`, `SiteCapabilityScope`, `AiContextScopeDuadpTrustTier`, `ProjectContextScope`	!45	🔄 MR open — 5 plugins fixed + type
`drupal/kb_cache`	`private/kb_cache`	`PlanStatusScope`, `PlanDomainScope`, `WorkspaceScope`	!77	🔄 MR open — 3 plugins fixed

`composer.json` type — `drupal-custom-module` required¶

All Bluefly-owned Drupal modules must declare:

{
  "type": "drupal-custom-module"
}

Not "drupal-module".

Why this matters¶

Consumer sites map installer-paths like this:

"web/modules/contrib/{$name}": ["type:drupal-module"],
"web/modules/custom/{$name}":  ["type:drupal-custom-module"]

A Bluefly module with type: drupal-module installs to web/modules/contrib/, which is: - Excluded from site git (Composer-managed path) - Overwritten on every composer install - Orphans any local patches

The correct target is web/modules/custom/, which is tracked, persistent, and correct for Bluefly-owned packages.

Sites verified¶

Site	Route for `drupal-custom-module`
`contextcontrol-ai`	`web/modules/custom/{$name}` ✅
`bluefly.io`	`web/modules/custom/{$name}` ✅

Both sites are correctly configured. The fix is only in the upstream composer.json type.

Consumer site actions post-merge¶

Once all 4 MRs are merged and tagged:

contextcontrol-ai¶

# ai_agents_agui: on dev-release/v0.1.x — auto-picks up
# ai_agents_ossa: on ^1.1@dev — auto-picks up
# kb_cache: on dev-release/v0.1.x — auto-picks up
# duadp: pinned to 0.1.9 — MUST bump after !45 tags
composer require drupal/duadp:<new-version> --no-update
composer update drupal/ai_agents_agui drupal/ai_agents_ossa drupal/kb_cache drupal/duadp
drush cr

bluefly.io¶

# bluefly.io is still on ai_context 1.0.0-beta4 — NOT affected by RC1 yet
# ai_agents_ossa: on ^0.1.2 — auto-picks up after !225 tags
# duadp: on dev-release/v0.1.x — auto-picks up after !45 merges
composer update drupal/ai_agents_ossa drupal/duadp
drush cr

FAILED APPROACH — Record for future agents¶

ATTEMPT=
Patch AiContextScope plugins directly inside
contextcontrol-ai/web/modules/contrib/ (ai_agents_ossa, ai_agents_agui, duadp)

RESULT=REJECTED

EVIDENCE=
web/modules/contrib/ is a Composer-managed path excluded from site git.
Changes are wiped on every composer install. The contextcontrol-ai .gitignore
confirms: web/modules/ is intentionally untracked.

REPLACEMENT=
Fix canonical GitLab repos via Gas City worktrees, open MRs.

WHEN_TO_RECONSIDER=Never for governed Bluefly packages.

Authoring new AiContextScope plugins — RC1 template¶

<?php

declare(strict_types=1);

namespace Drupal\your_module\Plugin\AiContextScope;

use Drupal\ai_context\Attribute\AiContextScope;
use Drupal\ai_context\Plugin\AiContextScope\AiContextScopeBase;
use Drupal\Core\StringTranslation\TranslatableMarkup;

/**
 * Your scope description.
 */
#[AiContextScope(
  id: 'your_scope_id',
  label: new TranslatableMarkup('Your Label'),
  description: new TranslatableMarkup('Your description.'),
)]
class YourScope extends AiContextScopeBase {

  /**
   * {@inheritdoc}
   */
  protected function doGetCurrentValue(): ?string {
    return NULL;
  }

  /**
   * {@inheritdoc}
   */
  protected function doGetDetectedValue(): ?string {
    return NULL;
  }

  /**
   * {@inheritdoc}
   */
  public function getValues(): array {
    return [];
  }

}