feat(sdk): applySiblingLinks — link sibling-repo packages during workflow setup

[khaliqgant]

Summary

Adds a generic, language-agnostic helper applySiblingLinks to @agent-relay/sdk/workflows that workflow authors chain into their setup. When a workflow consumes a package that lives in a sibling repo on disk (common in our monorepo-of-repos setup), linking redirects the package at dev-time to the sibling's current build output.

Why

In a recent sage wire-up workflow (AgentWorkforce/sage#105), agents writing code against @agent-assistant/proactive hit a version mismatch: npm install resolved an older published version that didn't have the exports the workflow needed. Rather than stopping, agents reached for declare module "@agent-assistant/proactive" { ... } augmentations and ~200 lines of fallback implementations to keep their code compiling. Tests type-checked against the fiction, the 80-to-100 gate passed, the PR shipped code that couldn't integrate with the real package.

Root cause: agents only see node_modules at workflow-run time, not what the sibling repo actually exposes on disk. Preflight export checks (option A) and prompt rules forbidding augmentation (option B) catch symptoms. Linking removes the wall entirely — agents see the head-of-main interface, no fabrication needed.

Public API

import { workflow, applySiblingLinks } from '@agent-relay/sdk/workflows';

const wf = applySiblingLinks(workflow('my-feature').pattern('dag'), {
  dependsOn: ['install-deps'],
  links: [
    {
      name: '@agent-assistant/proactive',
      path: '../agent-assistant/packages/proactive',
      expect: ['recordSignal', 'drainSignals'],
    },
  ],
});

Auto-detects the sibling's manifest and dispatches:

Manifest	Mechanism	Modifies committed files?
package.json	npm link (symlinks into node_modules)	No
pyproject.toml / setup.py / setup.cfg	uv pip install -e or pip install -e	No

When expect is provided, the step runs a post-link smoke import (node --input-type=module -e for npm, python3 -c for python) and fails if any named export is missing. That's the final guardrail: even if the link command succeeded, if the real interface doesn't match what the workflow expects, we fail before an agent writes a single line.

MVP scope

• npm + python. Auto-detected by manifest presence.
• Fail-fast on: missing sibling path, unknown manifest, link command failure, missing expected export.
• Other languages (Go replace directive, Cargo .cargo/config.toml [patch], Gradle includeBuild, Bundler bundle config local, .NET ProjectReference) land as new branches of the per-link dispatch behind the same applySiblingLinks API. None require public-API changes.

Test plan

• 12 unit tests: manifest detection, failure modes, quote escaping through the bash -c '...' wrapper, expect-list JSON survival through env var round-trip, builder integration, custom step name / dependsOn
• Typecheck clean against the new file
• Exercise end-to-end in sage's next workflow (wire the helper into applySageRepoSetup once this SDK version publishes)

Follow-ups (not this PR)

1. Update the writing-agent-relay-workflows skill rule with a new Rule 10: "workflows consuming a sibling-repo package MUST declare it via applySiblingLinks"
2. Retrofit applySageRepoSetup + applyAgentAssistantRepoSetup to use this
3. Add dispatch branches for Go / Cargo / Gradle as demand appears

---

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: aad13197ab

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Fall back to pip when uv cannot install outside a venv

The Python branch always prefers uv when it is present, but uv pip install -e fails in environments without an active virtualenv unless --system is provided; I verified this behavior with uv pip install pip --dry-run (No virtual environment found ... pass --system). Because this code runs under set -e, that failure exits immediately and never reaches the pip/pip3 fallback, so sibling-link setup fails on hosts that have uv installed globally but rely on plain pip workflows.

Useful? React with 👍 / 👎.

[khaliqgant]

Fixed in 8f17750. Added --system to the uv invocation AND wrapped it in if command -v uv && uv pip install --system ...; then : so a uv failure (in any environment) falls through to pip/pip3 via the elif chain rather than exiting under set -e. New test case covers the wrapping pattern.