dooers-protocol 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,7 @@
1
+ dist/
2
+ *.egg-info
3
+ .pytest_cache
4
+ .ruff_cache
5
+ .mypy_cache
6
+ __pycache__/
7
+ .venv/
@@ -0,0 +1,39 @@
1
+ Metadata-Version: 2.4
2
+ Name: dooers-protocol
3
+ Version: 0.1.0
4
+ Summary: Dooers — wire protocol shared between CLI and dooers-push service
5
+ Project-URL: Repository, https://github.com/Dooers-ai/dooers-cli
6
+ Author-email: Dooers <dev@dooers.ai>
7
+ License-Expression: MIT
8
+ Keywords: cli,dooers,protocol,pydantic
9
+ Requires-Python: >=3.10
10
+ Requires-Dist: pydantic>=2.13.2
11
+ Provides-Extra: dev
12
+ Requires-Dist: build>=1.4.3; extra == 'dev'
13
+ Requires-Dist: mypy>=1.20.1; extra == 'dev'
14
+ Requires-Dist: poethepoet>=0.44.0; extra == 'dev'
15
+ Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
16
+ Requires-Dist: pytest>=9.0.3; extra == 'dev'
17
+ Requires-Dist: ruff>=0.15.11; extra == 'dev'
18
+ Description-Content-Type: text/markdown
19
+
20
+ # dooers-protocol
21
+
22
+ Shared Pydantic models defining the wire contract between any Dooers client (`dooers-cli`, future SDKs) and the `dooers-push` Cloud Run service.
23
+
24
+ `PROTOCOL_VERSION` is exported from the package root.
25
+
26
+ ## Modules
27
+
28
+ - `auth` — `AuthSession`, `WhoamiResponse`.
29
+ - `agents` — `AgentRecord`, `CreateAgentRequest`, `AgentManifest` (the `dooers.yaml` schema).
30
+ - `push` — `PushRequest`, `PushResponse`, `BuildStatus`.
31
+ - `audit` — `AuditReport`, `AuditFinding`, `InfraManifest` (used by the auditor pipeline step).
32
+ - `errors` — `ErrorCode`, `ErrorEnvelope`.
33
+
34
+ ## Use
35
+
36
+ ```python
37
+ from dooers_protocol import PROTOCOL_VERSION
38
+ from dooers_protocol.push import PushResponse, BuildStatus
39
+ ```
@@ -0,0 +1,20 @@
1
+ # dooers-protocol
2
+
3
+ Shared Pydantic models defining the wire contract between any Dooers client (`dooers-cli`, future SDKs) and the `dooers-push` Cloud Run service.
4
+
5
+ `PROTOCOL_VERSION` is exported from the package root.
6
+
7
+ ## Modules
8
+
9
+ - `auth` — `AuthSession`, `WhoamiResponse`.
10
+ - `agents` — `AgentRecord`, `CreateAgentRequest`, `AgentManifest` (the `dooers.yaml` schema).
11
+ - `push` — `PushRequest`, `PushResponse`, `BuildStatus`.
12
+ - `audit` — `AuditReport`, `AuditFinding`, `InfraManifest` (used by the auditor pipeline step).
13
+ - `errors` — `ErrorCode`, `ErrorEnvelope`.
14
+
15
+ ## Use
16
+
17
+ ```python
18
+ from dooers_protocol import PROTOCOL_VERSION
19
+ from dooers_protocol.push import PushResponse, BuildStatus
20
+ ```
@@ -0,0 +1,60 @@
1
+ [project]
2
+ name = "dooers-protocol"
3
+ version = "0.1.0"
4
+ description = "Dooers — wire protocol shared between CLI and dooers-push service"
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ requires-python = ">=3.10"
8
+ authors = [
9
+ {name = "Dooers", email = "dev@dooers.ai"},
10
+ ]
11
+ keywords = ["dooers", "protocol", "pydantic", "cli"]
12
+ dependencies = [
13
+ "pydantic>=2.13.2",
14
+ ]
15
+
16
+ [project.urls]
17
+ Repository = "https://github.com/Dooers-ai/dooers-cli"
18
+
19
+ [build-system]
20
+ requires = ["hatchling"]
21
+ build-backend = "hatchling.build"
22
+
23
+ [tool.hatch.build.targets.wheel]
24
+ packages = ["src/dooers_protocol"]
25
+
26
+ [project.optional-dependencies]
27
+ dev = [
28
+ "mypy>=1.20.1",
29
+ "poethepoet>=0.44.0",
30
+ "pytest>=9.0.3",
31
+ "pytest-cov>=7.1.0",
32
+ "ruff>=0.15.11",
33
+ "build>=1.4.3",
34
+ ]
35
+
36
+ [tool.ruff]
37
+ line-length = 100
38
+ target-version = "py310"
39
+
40
+ [tool.ruff.lint]
41
+ select = ["E", "F", "I", "UP"]
42
+
43
+ [tool.ruff.lint.per-file-ignores]
44
+ "tests/*" = ["F401"]
45
+
46
+ [tool.ruff.format]
47
+ quote-style = "double"
48
+
49
+ [tool.pytest.ini_options]
50
+ testpaths = ["tests"]
51
+
52
+ [tool.poe.tasks]
53
+ format = "ruff format ."
54
+ check = "ruff check ."
55
+ "check:fix" = "ruff check --fix ."
56
+ typecheck = "mypy src/dooers_protocol"
57
+ test = "pytest"
58
+ "test:cov" = "pytest --cov=src --cov-report=term-missing"
59
+ dev = ["check", "typecheck", "test"]
60
+ build = "python -m build"
@@ -0,0 +1,5 @@
1
+ """dooers-protocol — wire contract between Dooers clients and dooers-push."""
2
+
3
+ PROTOCOL_VERSION = "2"
4
+
5
+ __all__ = ["PROTOCOL_VERSION"]
@@ -0,0 +1,71 @@
1
+ """Agent records, create requests, and the dooers.yaml manifest schema (core v2)."""
2
+
3
+ from datetime import datetime
4
+ from typing import Literal
5
+
6
+ from pydantic import BaseModel, ConfigDict
7
+
8
+
9
+ class AgentRecord(BaseModel):
10
+ agent_id: str
11
+ name: str
12
+ owner_user_id: str | None = None
13
+ organization_id: str | None = None
14
+ host_url: str | None = None
15
+ created_at: datetime | None = None
16
+ updated_at: datetime | None = None
17
+
18
+
19
+ class CreateAgentRequest(BaseModel):
20
+ organization_id: str
21
+ name: str
22
+
23
+
24
+ class WhatsAppConfig(BaseModel):
25
+ """Optional WhatsApp inbound. `path` is appended to the deployed host."""
26
+ model_config = ConfigDict(extra="forbid")
27
+ enabled: bool = False
28
+ path: str | None = None
29
+
30
+
31
+ class ProfileConfig(BaseModel):
32
+ """Listing/marketing profile (maps to core `profile`)."""
33
+ model_config = ConfigDict(extra="forbid")
34
+ summary: str | None = None
35
+ image_url: str | None = None
36
+ capabilities: list[str] = []
37
+ tools: list[str] = []
38
+ usage_limits: list[str] = []
39
+
40
+
41
+ class SuggestedPrompt(BaseModel):
42
+ """A shortcut shown below the chat greeting."""
43
+ model_config = ConfigDict(extra="forbid")
44
+ title: str
45
+ prompt: str
46
+
47
+
48
+ class UiConfig(BaseModel):
49
+ """Dooers chat-UI chrome (maps to core `settings.dooersUi_settings`)."""
50
+ model_config = ConfigDict(extra="forbid")
51
+ hide_mic: bool | None = None
52
+ hide_textinput: bool | None = None
53
+ hide_attachments: bool | None = None
54
+ suggested_prompts: list[SuggestedPrompt] = []
55
+
56
+
57
+ class AgentManifest(BaseModel):
58
+ """Schema of `dooers.yaml`. Written by `dooers agents create`, applied by `dooers push`."""
59
+ model_config = ConfigDict(extra="forbid")
60
+ protocol_version: str
61
+ agent_id: str
62
+ name: str
63
+ organization_id: str
64
+ description: str | None = None
65
+ # Path your agent serves the SDK messages endpoint on (e.g. "/" or "/agent").
66
+ # Combined with the deployed host → serverConfig.apiMessagesUrl.
67
+ message_path: str | None = None
68
+ message_scheme: Literal["wss", "https"] = "wss"
69
+ whatsapp: WhatsAppConfig | None = None
70
+ profile: ProfileConfig | None = None
71
+ ui: UiConfig | None = None
@@ -0,0 +1,32 @@
1
+ """Audit + infra-manifest shapes used by the auditor pipeline step.
2
+
3
+ In the POC, the auditor step returns AuditReport(passed=True, findings=[]).
4
+ These shapes are committed now so the future real auditor implementation
5
+ drops in without touching callers.
6
+ """
7
+
8
+ from typing import Literal
9
+
10
+ from pydantic import BaseModel
11
+
12
+
13
+ class AuditFinding(BaseModel):
14
+ severity: Literal["info", "warning", "error"]
15
+ category: str
16
+ message: str
17
+ file: str | None = None
18
+ line: int | None = None
19
+
20
+
21
+ class InfraManifest(BaseModel):
22
+ """What infrastructure the agent code declares (or is detected to need)."""
23
+
24
+ needs_db: bool = False
25
+ needs_redis: bool = False
26
+ detected_endpoints: list[str] = []
27
+
28
+
29
+ class AuditReport(BaseModel):
30
+ passed: bool
31
+ findings: list[AuditFinding] = []
32
+ required_infra: InfraManifest = InfraManifest()
@@ -0,0 +1,17 @@
1
+ """Auth-related wire shapes (session, whoami)."""
2
+
3
+ from pydantic import BaseModel
4
+
5
+
6
+ class AuthSession(BaseModel):
7
+ """A verified session returned by core's /session/verify."""
8
+
9
+ user_id: str
10
+ email: str
11
+
12
+
13
+ class WhoamiResponse(BaseModel):
14
+ """Response shape for `dooers whoami`."""
15
+
16
+ user_id: str
17
+ email: str
@@ -0,0 +1,25 @@
1
+ """Common error envelope returned by dooers-push for non-2xx responses."""
2
+
3
+ from enum import Enum
4
+
5
+ from pydantic import BaseModel
6
+
7
+
8
+ class ErrorCode(str, Enum):
9
+ unauthenticated = "unauthenticated"
10
+ forbidden = "forbidden"
11
+ not_found = "not_found"
12
+ archive_too_large = "archive_too_large"
13
+ audit_failed = "audit_failed"
14
+ build_failed = "build_failed"
15
+ build_timeout = "build_timeout"
16
+ core_unreachable = "core_unreachable"
17
+ lb_registration_failed = "lb_registration_failed"
18
+ internal = "internal"
19
+
20
+
21
+ class ErrorEnvelope(BaseModel):
22
+ error_code: ErrorCode
23
+ message: str
24
+ correlation_id: str
25
+ details: dict = {}
@@ -0,0 +1,31 @@
1
+ """Push request/response shapes and build status enum."""
2
+
3
+ from enum import Enum
4
+
5
+ from pydantic import BaseModel
6
+
7
+ from dooers_protocol.audit import AuditReport
8
+
9
+
10
+ class BuildStatus(str, Enum):
11
+ queued = "queued"
12
+ building = "building"
13
+ deploying = "deploying"
14
+ succeeded = "succeeded"
15
+ failed = "failed"
16
+
17
+
18
+ class PushRequest(BaseModel):
19
+ agent_id: str
20
+ tag: str = "latest"
21
+ env: str = "prod"
22
+
23
+
24
+ class PushResponse(BaseModel):
25
+ agent_id: str
26
+ build_id: str
27
+ image: str
28
+ status: BuildStatus
29
+ url: str | None = None
30
+ error: str | None = None
31
+ audit: AuditReport | None = None
File without changes
File without changes
@@ -0,0 +1,165 @@
1
+ import pytest
2
+ from pydantic import ValidationError
3
+
4
+ from dooers_protocol.agents import (
5
+ AgentManifest,
6
+ AgentRecord,
7
+ CreateAgentRequest,
8
+ ProfileConfig,
9
+ SuggestedPrompt,
10
+ UiConfig,
11
+ WhatsAppConfig,
12
+ )
13
+
14
+
15
+ def test_manifest_ui_config_validates_and_forbids_extra():
16
+ m = AgentManifest(
17
+ protocol_version="2",
18
+ agent_id="ag-x",
19
+ name="x",
20
+ organization_id="org_1",
21
+ ui=UiConfig(hide_mic=True, suggested_prompts=[SuggestedPrompt(title="t", prompt="p")]),
22
+ )
23
+ assert m.ui.hide_mic is True
24
+ assert m.ui.suggested_prompts[0].title == "t"
25
+ with pytest.raises(ValidationError):
26
+ UiConfig(bogus=1) # type: ignore[call-arg]
27
+ with pytest.raises(ValidationError):
28
+ SuggestedPrompt(title="only-title") # type: ignore[call-arg] # missing prompt
29
+
30
+
31
+ def test_agent_record_v2_shape():
32
+ r = AgentRecord(
33
+ agent_id="550e8400-e29b-41d4-a716-446655440000",
34
+ name="x",
35
+ owner_user_id="user_1",
36
+ organization_id="org_1",
37
+ host_url=None,
38
+ )
39
+ assert r.host_url is None
40
+ assert r.organization_id == "org_1"
41
+
42
+
43
+ def test_create_agent_request_requires_org():
44
+ req = CreateAgentRequest(organization_id="org_1", name="x")
45
+ assert req.organization_id == "org_1"
46
+
47
+
48
+ def test_manifest_carries_org_and_uuid():
49
+ m = AgentManifest(
50
+ protocol_version="2",
51
+ agent_id="550e8400-e29b-41d4-a716-446655440000",
52
+ name="x",
53
+ organization_id="org_1",
54
+ )
55
+ assert m.organization_id == "org_1"
56
+
57
+
58
+ def test_manifest_rejects_unknown_field():
59
+ with pytest.raises(ValidationError):
60
+ AgentManifest(
61
+ protocol_version="2",
62
+ agent_id="u",
63
+ name="x",
64
+ organization_id="o",
65
+ runtime="docker", # removed field -> forbidden
66
+ )
67
+
68
+
69
+ # --- new config-field tests ---
70
+
71
+
72
+ def test_manifest_with_new_fields_validates():
73
+ m = AgentManifest(
74
+ protocol_version="2",
75
+ agent_id="550e8400-e29b-41d4-a716-446655440000",
76
+ name="my-agent",
77
+ organization_id="org_1",
78
+ description="A helpful agent",
79
+ message_path="/agent",
80
+ message_scheme="wss",
81
+ whatsapp=WhatsAppConfig(enabled=True, path="/whatsapp/inbound"),
82
+ profile=ProfileConfig(
83
+ summary="Does things",
84
+ image_url="https://example.com/img.png",
85
+ capabilities=["chat"],
86
+ tools=["search"],
87
+ usage_limits=["100/day"],
88
+ ),
89
+ )
90
+ assert m.description == "A helpful agent"
91
+ assert m.message_path == "/agent"
92
+ assert m.message_scheme == "wss"
93
+ assert m.whatsapp is not None
94
+ assert m.whatsapp.enabled is True
95
+ assert m.profile is not None
96
+ assert m.profile.summary == "Does things"
97
+ assert m.profile.capabilities == ["chat"]
98
+
99
+
100
+ def test_manifest_omitting_new_fields_is_backwards_compat():
101
+ """New optional fields must not break manifests that omit them."""
102
+ m = AgentManifest(
103
+ protocol_version="2",
104
+ agent_id="550e8400-e29b-41d4-a716-446655440000",
105
+ name="x",
106
+ organization_id="org_1",
107
+ )
108
+ assert m.description is None
109
+ assert m.message_path is None
110
+ assert m.message_scheme == "wss"
111
+ assert m.whatsapp is None
112
+ assert m.profile is None
113
+
114
+
115
+ def test_manifest_extra_forbid_still_rejects_top_level_unknown():
116
+ with pytest.raises(ValidationError):
117
+ AgentManifest(
118
+ protocol_version="2",
119
+ agent_id="u",
120
+ name="x",
121
+ organization_id="o",
122
+ unknown_top="oops",
123
+ )
124
+
125
+
126
+ def test_whatsapp_config_extra_forbid():
127
+ with pytest.raises(ValidationError):
128
+ WhatsAppConfig(enabled=True, path="/x", bogus="nope")
129
+
130
+
131
+ def test_profile_config_extra_forbid():
132
+ with pytest.raises(ValidationError):
133
+ ProfileConfig(summary="hi", unknown_field="oops")
134
+
135
+
136
+ def test_manifest_message_scheme_default_is_wss():
137
+ m = AgentManifest(
138
+ protocol_version="2",
139
+ agent_id="u",
140
+ name="x",
141
+ organization_id="o",
142
+ )
143
+ assert m.message_scheme == "wss"
144
+
145
+
146
+ def test_manifest_message_scheme_https_accepted():
147
+ m = AgentManifest(
148
+ protocol_version="2",
149
+ agent_id="u",
150
+ name="x",
151
+ organization_id="o",
152
+ message_scheme="https",
153
+ )
154
+ assert m.message_scheme == "https"
155
+
156
+
157
+ def test_manifest_message_scheme_invalid_rejected():
158
+ with pytest.raises(ValidationError):
159
+ AgentManifest(
160
+ protocol_version="2",
161
+ agent_id="u",
162
+ name="x",
163
+ organization_id="o",
164
+ message_scheme="ws", # type: ignore[arg-type]
165
+ )
@@ -0,0 +1,71 @@
1
+ """Smoke tests — verify each model round-trips JSON serialization."""
2
+
3
+ from datetime import datetime, timezone
4
+
5
+ from dooers_protocol import PROTOCOL_VERSION
6
+ from dooers_protocol.agents import AgentManifest, AgentRecord, CreateAgentRequest
7
+ from dooers_protocol.audit import AuditReport, InfraManifest
8
+ from dooers_protocol.errors import ErrorCode, ErrorEnvelope
9
+ from dooers_protocol.push import BuildStatus, PushResponse
10
+
11
+
12
+ def test_protocol_version_exported() -> None:
13
+ assert PROTOCOL_VERSION == "2"
14
+
15
+
16
+ def test_agent_record_roundtrip() -> None:
17
+ now = datetime.now(timezone.utc)
18
+ rec = AgentRecord(
19
+ agent_id="ag_8h2k",
20
+ name="customer-support",
21
+ owner_user_id="u_1",
22
+ created_at=now,
23
+ updated_at=now,
24
+ )
25
+ assert AgentRecord.model_validate_json(rec.model_dump_json()) == rec
26
+
27
+
28
+ def test_agent_manifest_rejects_unknown_fields() -> None:
29
+ import pytest
30
+ from pydantic import ValidationError
31
+
32
+ with pytest.raises(ValidationError):
33
+ AgentManifest(
34
+ protocol_version="2",
35
+ agent_id="550e8400-e29b-41d4-a716-446655440000",
36
+ name="x",
37
+ organization_id="org_1",
38
+ unknown_field="oops", # type: ignore[call-arg]
39
+ )
40
+
41
+
42
+ def test_push_response_succeeded_has_url() -> None:
43
+ resp = PushResponse(
44
+ agent_id="ag_8h2k",
45
+ build_id="op_1",
46
+ image="us-central1-docker.pkg.dev/p/agents/ag_8h2k:latest",
47
+ status=BuildStatus.succeeded,
48
+ url="https://ag-8h2k-prod-xxx.run.app",
49
+ )
50
+ assert resp.url is not None
51
+
52
+
53
+ def test_audit_report_default_passes() -> None:
54
+ rep = AuditReport(passed=True)
55
+ assert rep.findings == []
56
+ assert rep.required_infra == InfraManifest()
57
+
58
+
59
+ def test_error_envelope() -> None:
60
+ env = ErrorEnvelope(
61
+ error_code=ErrorCode.unauthenticated,
62
+ message="bad token",
63
+ correlation_id="abc",
64
+ )
65
+ assert env.error_code == ErrorCode.unauthenticated
66
+
67
+
68
+ def test_create_agent_request_requires_org() -> None:
69
+ req = CreateAgentRequest(organization_id="org_1", name="my-agent")
70
+ assert req.organization_id == "org_1"
71
+ assert req.name == "my-agent"