Skip to content

feat: add advisory-only host contract v1 - #55

Merged
jhuang-tw merged 25 commits into
mainfrom
feature/advisory-host-contract-v1
Aug 5, 2026
Merged

feat: add advisory-only host contract v1#55
jhuang-tw merged 25 commits into
mainfrom
feature/advisory-host-contract-v1

Conversation

@jhuang-tw

Copy link
Copy Markdown
Owner

Summary

Adds a separate, versioned, advisory-only host contract for external workflow authorities such as AutoGPT, without changing djobs-native task ownership semantics.

Base is pinned to v0.19.0 commit 46eff8a1227dc256592a237c9a0af8ba7706d528.

New additive surfaces

  • djobs contract --schema-major 1 capabilities
  • djobs contract --schema-major 1 observation ...
  • djobs contract --schema-major 1 receipt ...
  • djobs-contract
  • djobs-contract-mcp

The standalone MCP exposes only capabilities, observation, and receipt verification. It does not register agents or expose checkpoint / handoff.

Contract guarantees

  • authority=advisory
  • side_effects=false
  • writes_database=false
  • SQLite is opened with mode=ro and PRAGMA query_only=ON
  • no agent registration, lease recovery, snapshot capture, task claim, task completion, scheduling, or worktree creation
  • repository fingerprint / HEAD mismatch fails open
  • structured filters run in the SQLite query stage
  • typed per-observation provenance, lifecycle status, freshness, evidence hash, ranking signals
  • explicit token-budget and truncation metadata
  • query/output audit receipt
  • ASCII-safe JSON transport for CP950/Windows consoles

Compatibility

Existing djobs.entrypoint, coding MCP, checkpoint, handoff, queue, scheduler, and storage semantics remain unchanged. The public console dispatcher delegates every non-contract command to the established entrypoint.

Schema major 1 is additive within the major; consumers ignore unknown fields, and a new major requires explicit opt-in.

Validation

Focused isolated tests before push: 10 passed.

Added tests cover:

  • capability/authority boundary
  • exact repository HEAD + feature filtering
  • read-only database invariance
  • budget truncation and critical-failure disclosure
  • receipt hash verification/tamper detection
  • CP950-safe Chinese/emoji/path JSON
  • runtime JSON Schema validation
  • CLI schema negotiation and routing
  • golden fixtures

This is a draft until the repository's complete GitHub CI matrix is green.

@jhuang-tw
jhuang-tw marked this pull request as ready for review August 5, 2026 11:40
@jhuang-tw
jhuang-tw merged commit 2b9ef68 into main Aug 5, 2026
14 checks passed
@jhuang-tw
jhuang-tw deleted the feature/advisory-host-contract-v1 branch August 5, 2026 11:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant