darkings/dsh-agy-provider

dsh-agy-provider

简体中文 · English

Expose the locally authenticated AGY CLI as a model Provider for DSH.

The project lets DSH use the models and quota available to the user's AGY account while keeping DSH's conversations, Sessions, Web mode, and headless mode. The Provider does not call the Google Gemini API directly and does not store OAuth credentials. Authentication and model selection remain owned by the local agy CLI, while tool execution remains in DSH ToolRuntime.

Project status

0.10.0 is published to npm with latest=0.10.0. Building on 0.9.0's settings panel, workspace auto-detection, and model/effort separation, 0.10.0 adds optimized-full context budgets, deterministic tool-result eviction, privacy-safe diagnostics, and a Windows no-console launcher; sessionMode: full remains the default.

0.7.0 / 0.8.0 merged: v0.7.0 → b94fa32 (latest=0.7.0 released), v0.8.0 → b7c9a45 merged to main. Since 0.7.0 the bundle defaults to dsh-owned (DSH Session/ToolRuntime/sandbox/approval own the project and permissions).

0.10.0 highlights:

• Context and tool safety: DSH-owned structured prompts use a 56 KiB fail-closed limit, return AGY_INPUT_TOO_LARGE when exceeded, recover after compaction, and evict whole tool-result segments deterministically.

• Performance and observability: stable prefixes, canonical tool schemas, step-level usage accounting, and fingerprint diagnostics improve cache eligibility and make failures auditable without promising backend cacheRead hits.

• Settings panel: full zh-CN/en i18n via schemastery .i18n, registerConfigurableProviders(settingsNs dsh-agy-provider) + registerModelDiscovery, multi-select visible models and independent reasoning effort dropdown.

• Workspace-transparent: workspaceRoot deprecated (.deprecated(), hidden when dsh-owned), tool calls use DSH Session header.cwd + workspaceRegistry + sandboxPolicy transparently; pure text needs no workspace, tool without workspace returns actionable DSH_WORKSPACE_MISMATCH.

• Model/effort split: gemini-3.7-flash as base, reasoningEffort: low|medium|high separately; listModels returns bases with reasoning.efforts, legacy -high/-medium/-low suffix auto-compat with DEPRECATED_MODEL_EFFORT_SUFFIX.

• Model visibility: visibleModels: string[] empty = all, non-empty = only checked bases (explicit request still compat).

• Keeps the 0.7.0 DSH-owned tool bridge, Agent presets, doctor v5 (profileSchemaVersion: 4), zero retries, quota-free diagnostics, and cross-platform gates; imageInput: experimental now has an end-to-end multimodal path.

The image bridge remains experimental. When enabled it advertises inputModalities: ['text', 'image'] and uses a dedicated dsh-agy-image-view Agent for staged images. Real pixel answers, same-session follow-ups, stable failures, and cleanup were verified in DSH Desktop; this is still not an unconditional production image capability.

Architecture

User / DSH Web / DSH headless
              │
              ▼
      dsh-agy-provider
      ├─ DSH LlmAdapter
      ├─ Prompt / stream mapping
      ├─ Session / Conversation mapping
      ├─ Model discovery / retry / telemetry
      └─ Agent and workspace safety boundaries
              │
              ▼
      agy --output-format stream-json
              │
              ▼
      AGY account quota, models, and Agent tools

The Provider starts AGY with spawn(executable, args), without shell command composition. It incrementally parses AGY's line-delimited output and converts it into DSH text, usage, finish, and stable error events.

Capability matrix

Installation and usage

Requirements

• Node.js >=20.
• The local AGY CLI is installed, logged in, and available as agy on PATH.
• pnpm must be available when installing through the DSH profile plugin manager.

Install into a DSH profile

A normal npm install only installs the Node.js package. It does not modify a DSH profile. Use the native DSH plugin manager:

npx @deepseek-ai/dsh plugin --profile web add dsh-agy-provider@0.10.0
npx @deepseek-ai/dsh plugin --profile headless add dsh-agy-provider@0.10.0

The 0.9.0 bundle defaults (cordis.patch.yml) are equivalent to:

enabled: true
provider: agy
model: gemini-3.1-pro
agent: deepseek-proxy
toolPolicy: dsh-owned
sessionMode: full
imageInput: off

Direct library Config({}) remains enabled: false, toolPolicy: reject. Importing the package does not modify a user's DSH profile; BundleConfig is the explicit enabled: true / dsh-owned.

Agent preset configuration

Read-only (dsh-owned needs no workspaceRoot):

agentPreset: read-only
toolPolicy: dsh-owned
# no workspaceRoot needed; open the folder in DSH and the Session cwd is the project

Workspace write (dsh-owned still needs no manual dir; DSH permission preset decides):

agentPreset: workspace-write
toolPolicy: dsh-owned
# dsh-owned: workspaceRoot deprecated, DSH workspace-write / danger-full-access decides the boundary

Legacy agy-owned with explicit dir (not recommended):

agentPreset: workspace-write
toolPolicy: agy-owned
workspaceRoot: C:\work\my-project

Write access is enforced by DSH permission preset and sandbox; the provider does not bypass it.

Configuration example (0.9.0 recommended)

enabled: true
provider: agy
agent: deepseek-proxy
model: gemini-3.7-flash            # base id, pick reasoningEffort low/medium/high per-session in DSH
visibleModels:                      # panel-checked models, empty = all
  - gemini-3.7-flash
  - gemini-3.1-pro
models:
  - id: gemini-3.7-flash
    name: Gemini 3.7 Flash
  - id: gemini-3.1-pro
    name: Gemini 3.1 Pro
toolPolicy: dsh-owned
transport: one-shot                 # or persistent (opt-in, one worker per Session)
sessionMode: full
modelDiscovery: auto
retryPolicy:
  maxRetries: 5
  retryableCodes: [EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT]
imageInput: off

Compat: legacy model: gemini-3.7-flash-high still resolves to base + high with a warning; prefer base + per-session reasoningEffort.

Retries follow the DSH normal policy by default: up to five retries after the initial request, including TIMEOUT (at most six AGY requests total). retryPolicy can narrow the count and error-code allowlist in settings.yaml.

Diagnostics and development

Quota-free diagnostics:

npm run diagnose -- --json
npx dsh-agy-provider doctor --profile web --json
npx dsh-agy-provider agents list

Local development:

npm ci
npm run verify
npm run benchmark
npm run smoke:dsh:self-contained

Experiments that call a real AGY model never run automatically. The 0.9.0 multimodal loop was completed under explicit quota authorization; future runs must not consume real-model quota again without authorization.

Roadmap

Future work follows the same rules: verifiable behavior, safe fallback, and bounded quota use.

0.7.0: DSH-controlled workspace, permissions, and tools (implemented)

• The base DSH-owned tool bridge is implemented: AGY emits locally validated DSH tool calls, while DSH ToolRuntime executes filesystem, shell, network, and MCP tools.
• The V7-M4 permission matrix and cross-platform CI, V7-M5 doctor v3/allowlisted telemetry/security regressions, and V7-M6 packed artifact/Web/headless/release gates are complete.
• Use the DSH Session project cwd and its read-only, workspace-write, or danger-full-access selection instead of duplicating switches in this plugin.
• Keep sandboxing, approval, MCP credentials, and side effects inside DSH; the Provider does not pass --dangerously-skip-permissions.
• See the 0.7.0 development plan for scope, security gates, quota budget, and milestones.

0.8.0: persistent transport and DSH next compatibility (implemented)

• AGY 1.1.15's official stream-json input as a stable, session-affine opt-in transport; one-shot remains the default (transport: persistent explicit).
• Validated both DSH rc.7 stable and rc.8 next isolated lanes without breaking stable; warm-turn 79% improvement, 145/145.
• Delivered image modality as a limited 0.9.0 experimental capability, with Desktop pixel answers, follow-ups, stable failures, and cleanup verified.
• See the 0.8.0 development plan for scope, go/no-go criteria, quota budget, and release gates.

0.9.0: settings panel + workspace-transparent + model parity (implemented)

• Settings panel: Config i18n (zh-CN/en) + registerConfigurableProviders + registerModelDiscovery, visibleModels multi-select and base + reasoningEffort split.
• Workspace-transparent: workspaceRoot deprecated under dsh-owned, project auto-owned by DSH Session, text needs no workspace.
• Full 7-layer tests (L1 160+ / L2 integration / L3 self-contained / L4 permission matrix / L5 settings panel / L6 cross-platform / L7 real sampling) and doctor v5 (profileSchemaVersion 4).
• See 0.9.0 development plan and 0.9.0 migration guide.

Later: image and tool UX hardening

• Continue hardening the DSH Web AttachmentStore → AGY pixel-answer path for performance, more formats, and cross-platform evidence.
• Improve workspace-write conflict handling, backup, rollback, and tool-call presentation.
• Never bypass the DSH session permission preset merely because a write tool exists in the catalog.

Later: transport and cost optimization

• 0.8.0 persistent transport already passed real AGY protocol, isolation, crash recovery, process cleanup and token-cost gates (V8-M4 go); 0.9.0 keeps it opt-in.
• Continue purpose-aware compaction/session-title routing, usage observability and evaluation of default persistent.
• Keep CI, doctor, parser, and Mock smoke quota-free.

Explicit non-goals

• Calling the Gemini API directly or managing OAuth/refresh tokens inside the plugin.
• A dual DSH/AGY tool-execution loop.
• Unverified glob, shell, network, MCP, subagent, or automatic permission approval capabilities.
• Default writes to a user's workspace.
• Unrestricted production image modality, temperature, stop, maxTokens, or unverified reasoning-delta output.
• Production persistent stream transport before cost and reliability evidence exists.

Project structure

dsh-agy-provider/
├─ src/
│  ├─ provider/       # DSH Adapter, config, serialization, image bridge
│  ├─ agy/            # process, argv, stream-json, discovery, redaction (incl. persistent-transport)
│  ├─ session/        # DSH Session to AGY Conversation mapping
│  ├─ doctor.ts       # profile-aware doctor v5 (profileSchemaVersion 4)
│  ├─ dsh/context.ts  # DSH Session/workspace/sandbox/approval transparent check
│  └─ agent-*.ts      # presets, installer, and agents CLI
├─ agents/            # tool-free/read-only/workspace-write templates
├─ scripts/           # verify, benchmark, diagnose, and DSH smoke
├─ tests/             # L1 unit + L2 integration (visibleModels/normalization/i18n)
├─ docs/
├─ cordis.patch.yml
└─ package.json

Documentation

• Installation (0.9.0 workspace-transparent & visibleModels)
• 0.9.0 migration guide (base+effort / visibility / deprecated workspaceRoot)
• 0.9.0 development plan (panel/workspace/parity/7-layer tests)
• 0.9.0 release checklist (L1~L7 gates)
• Tool capability matrix
• Compatibility matrix
• DSH Provider contract
• 0.8.0 / 0.7.0 development plans & migration guides (history)
• CHANGELOG
• Performance baseline

License

MIT