artemys 0.2.1 → 0.3.2

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.
Files changed (184) hide show
  1. package/README.md +111 -175
  2. package/dist/cli/config.d.ts +21 -0
  3. package/dist/cli/config.d.ts.map +1 -0
  4. package/dist/cli/config.js +97 -0
  5. package/dist/cli/config.js.map +1 -0
  6. package/dist/cli/index.d.ts +5 -0
  7. package/dist/cli/index.d.ts.map +1 -1
  8. package/dist/cli/index.js +147 -189
  9. package/dist/cli/index.js.map +1 -1
  10. package/dist/cli/init.d.ts +3 -0
  11. package/dist/cli/init.d.ts.map +1 -0
  12. package/dist/cli/init.js +174 -0
  13. package/dist/cli/init.js.map +1 -0
  14. package/dist/coffeeshop/client.d.ts +24 -101
  15. package/dist/coffeeshop/client.d.ts.map +1 -1
  16. package/dist/coffeeshop/client.js +102 -153
  17. package/dist/coffeeshop/client.js.map +1 -1
  18. package/dist/coffeeshop/index.d.ts +2 -1
  19. package/dist/coffeeshop/index.d.ts.map +1 -1
  20. package/dist/coffeeshop/index.js +2 -0
  21. package/dist/coffeeshop/index.js.map +1 -1
  22. package/dist/coffeeshop/schemas.d.ts +146 -0
  23. package/dist/coffeeshop/schemas.d.ts.map +1 -0
  24. package/dist/coffeeshop/schemas.js +115 -0
  25. package/dist/coffeeshop/schemas.js.map +1 -0
  26. package/dist/discovery/agent-card.schema.d.ts +4 -2
  27. package/dist/discovery/agent-card.schema.d.ts.map +1 -1
  28. package/dist/discovery/agent-card.schema.js +10 -2
  29. package/dist/discovery/agent-card.schema.js.map +1 -1
  30. package/dist/discovery/index.d.ts +2 -4
  31. package/dist/discovery/index.d.ts.map +1 -1
  32. package/dist/discovery/index.js +2 -4
  33. package/dist/discovery/index.js.map +1 -1
  34. package/dist/discovery/reserved-handles.d.ts +2 -0
  35. package/dist/discovery/reserved-handles.d.ts.map +1 -0
  36. package/dist/discovery/reserved-handles.js +18 -0
  37. package/dist/discovery/reserved-handles.js.map +1 -0
  38. package/dist/integrations/job-boards/http.d.ts +4 -1
  39. package/dist/integrations/job-boards/http.d.ts.map +1 -1
  40. package/dist/integrations/job-boards/http.js +4 -3
  41. package/dist/integrations/job-boards/http.js.map +1 -1
  42. package/dist/integrations/job-boards/remotive.d.ts.map +1 -1
  43. package/dist/integrations/job-boards/remotive.js +6 -35
  44. package/dist/integrations/job-boards/remotive.js.map +1 -1
  45. package/dist/mcp-server/__tests__/test-fixtures.d.ts +39 -0
  46. package/dist/mcp-server/__tests__/test-fixtures.d.ts.map +1 -0
  47. package/dist/mcp-server/__tests__/test-fixtures.js +87 -0
  48. package/dist/mcp-server/__tests__/test-fixtures.js.map +1 -0
  49. package/dist/mcp-server/index.d.ts +1 -1
  50. package/dist/mcp-server/index.d.ts.map +1 -1
  51. package/dist/mcp-server/index.js +1 -1
  52. package/dist/mcp-server/index.js.map +1 -1
  53. package/dist/mcp-server/persistence.d.ts +0 -4
  54. package/dist/mcp-server/persistence.d.ts.map +1 -1
  55. package/dist/mcp-server/persistence.js +25 -30
  56. package/dist/mcp-server/persistence.js.map +1 -1
  57. package/dist/mcp-server/server.d.ts +2 -3
  58. package/dist/mcp-server/server.d.ts.map +1 -1
  59. package/dist/mcp-server/server.js +16 -6
  60. package/dist/mcp-server/server.js.map +1 -1
  61. package/dist/mcp-server/state.d.ts +0 -1
  62. package/dist/mcp-server/state.d.ts.map +1 -1
  63. package/dist/mcp-server/state.js +0 -4
  64. package/dist/mcp-server/state.js.map +1 -1
  65. package/dist/mcp-server/tools/common.d.ts +1 -199
  66. package/dist/mcp-server/tools/common.d.ts.map +1 -1
  67. package/dist/mcp-server/tools/common.js +1 -3
  68. package/dist/mcp-server/tools/common.js.map +1 -1
  69. package/dist/mcp-server/tools/index.d.ts.map +1 -1
  70. package/dist/mcp-server/tools/index.js +2 -4
  71. package/dist/mcp-server/tools/index.js.map +1 -1
  72. package/dist/mcp-server/tools/messaging.d.ts +14 -0
  73. package/dist/mcp-server/tools/messaging.d.ts.map +1 -0
  74. package/dist/mcp-server/tools/messaging.js +39 -0
  75. package/dist/mcp-server/tools/messaging.js.map +1 -0
  76. package/dist/mcp-server/tools/protocol.d.ts.map +1 -1
  77. package/dist/mcp-server/tools/protocol.js +0 -28
  78. package/dist/mcp-server/tools/protocol.js.map +1 -1
  79. package/dist/mcp-server/tools/talent.d.ts +18 -0
  80. package/dist/mcp-server/tools/talent.d.ts.map +1 -1
  81. package/dist/mcp-server/tools/talent.js +60 -188
  82. package/dist/mcp-server/tools/talent.js.map +1 -1
  83. package/dist/openclaw/skill.js +1 -1
  84. package/dist/openclaw/skill.js.map +1 -1
  85. package/dist/protocol/dialogue.schema.d.ts +26 -6
  86. package/dist/protocol/dialogue.schema.d.ts.map +1 -1
  87. package/dist/protocol/dialogue.schema.js +11 -0
  88. package/dist/protocol/dialogue.schema.js.map +1 -1
  89. package/dist/protocol/envelope.schema.d.ts +11 -5
  90. package/dist/protocol/envelope.schema.d.ts.map +1 -1
  91. package/dist/protocol/envelope.schema.js +4 -2
  92. package/dist/protocol/envelope.schema.js.map +1 -1
  93. package/dist/protocol/handshake.schema.d.ts +4 -2
  94. package/dist/protocol/handshake.schema.d.ts.map +1 -1
  95. package/dist/protocol/index.d.ts +2 -3
  96. package/dist/protocol/index.d.ts.map +1 -1
  97. package/dist/protocol/index.js +2 -3
  98. package/dist/protocol/index.js.map +1 -1
  99. package/dist/protocol/message-types.d.ts +2 -1
  100. package/dist/protocol/message-types.d.ts.map +1 -1
  101. package/dist/protocol/message-types.js +1 -0
  102. package/dist/protocol/message-types.js.map +1 -1
  103. package/dist/protocol/message.schema.d.ts +35 -12
  104. package/dist/protocol/message.schema.d.ts.map +1 -1
  105. package/dist/protocol/message.schema.js +4 -2
  106. package/dist/protocol/message.schema.js.map +1 -1
  107. package/dist/protocol/resolution.schema.d.ts +8 -4
  108. package/dist/protocol/resolution.schema.d.ts.map +1 -1
  109. package/dist/protocol/state-machine.d.ts.map +1 -1
  110. package/dist/protocol/state-machine.js +2 -1
  111. package/dist/protocol/state-machine.js.map +1 -1
  112. package/dist/protocol/talent.schema.d.ts +115 -0
  113. package/dist/protocol/talent.schema.d.ts.map +1 -1
  114. package/dist/protocol/talent.schema.js +61 -3
  115. package/dist/protocol/talent.schema.js.map +1 -1
  116. package/dist/resume/index.d.ts +4 -0
  117. package/dist/resume/index.d.ts.map +1 -0
  118. package/dist/resume/index.js +4 -0
  119. package/dist/resume/index.js.map +1 -0
  120. package/dist/resume/parse-resume.d.ts +8 -0
  121. package/dist/resume/parse-resume.d.ts.map +1 -0
  122. package/dist/resume/parse-resume.js +117 -0
  123. package/dist/resume/parse-resume.js.map +1 -0
  124. package/dist/resume/providers/anthropic.d.ts +2 -0
  125. package/dist/resume/providers/anthropic.d.ts.map +1 -0
  126. package/dist/resume/providers/anthropic.js +26 -0
  127. package/dist/resume/providers/anthropic.js.map +1 -0
  128. package/dist/resume/providers/google.d.ts +2 -0
  129. package/dist/resume/providers/google.d.ts.map +1 -0
  130. package/dist/resume/providers/google.js +24 -0
  131. package/dist/resume/providers/google.js.map +1 -0
  132. package/dist/resume/providers/openai.d.ts +2 -0
  133. package/dist/resume/providers/openai.d.ts.map +1 -0
  134. package/dist/resume/providers/openai.js +25 -0
  135. package/dist/resume/providers/openai.js.map +1 -0
  136. package/dist/resume/to-card.d.ts +7 -0
  137. package/dist/resume/to-card.d.ts.map +1 -0
  138. package/dist/resume/to-card.js +63 -0
  139. package/dist/resume/to-card.js.map +1 -0
  140. package/package.json +11 -6
  141. package/dist/discovery/intro-decision.schema.d.ts +0 -16
  142. package/dist/discovery/intro-decision.schema.d.ts.map +0 -1
  143. package/dist/discovery/intro-decision.schema.js +0 -10
  144. package/dist/discovery/intro-decision.schema.js.map +0 -1
  145. package/dist/discovery/intro-request.schema.d.ts +0 -10
  146. package/dist/discovery/intro-request.schema.d.ts.map +0 -1
  147. package/dist/discovery/intro-request.schema.js +0 -11
  148. package/dist/discovery/intro-request.schema.js.map +0 -1
  149. package/dist/discovery/session-bootstrap.schema.d.ts +0 -97
  150. package/dist/discovery/session-bootstrap.schema.d.ts.map +0 -1
  151. package/dist/discovery/session-bootstrap.schema.js +0 -100
  152. package/dist/discovery/session-bootstrap.schema.js.map +0 -1
  153. package/dist/mcp-server/tools/intro.d.ts +0 -3
  154. package/dist/mcp-server/tools/intro.d.ts.map +0 -1
  155. package/dist/mcp-server/tools/intro.js +0 -53
  156. package/dist/mcp-server/tools/intro.js.map +0 -1
  157. package/dist/protocol/transport.schema.d.ts +0 -27
  158. package/dist/protocol/transport.schema.d.ts.map +0 -1
  159. package/dist/protocol/transport.schema.js +0 -18
  160. package/dist/protocol/transport.schema.js.map +0 -1
  161. package/dist/transport/client.d.ts +0 -32
  162. package/dist/transport/client.d.ts.map +0 -1
  163. package/dist/transport/client.js +0 -155
  164. package/dist/transport/client.js.map +0 -1
  165. package/dist/transport/dedup.d.ts +0 -9
  166. package/dist/transport/dedup.d.ts.map +0 -1
  167. package/dist/transport/dedup.js +0 -36
  168. package/dist/transport/dedup.js.map +0 -1
  169. package/dist/transport/handler.d.ts +0 -9
  170. package/dist/transport/handler.d.ts.map +0 -1
  171. package/dist/transport/handler.js +0 -105
  172. package/dist/transport/handler.js.map +0 -1
  173. package/dist/transport/hmac.d.ts +0 -3
  174. package/dist/transport/hmac.d.ts.map +0 -1
  175. package/dist/transport/hmac.js +0 -43
  176. package/dist/transport/hmac.js.map +0 -1
  177. package/dist/transport/index.d.ts +0 -6
  178. package/dist/transport/index.d.ts.map +0 -1
  179. package/dist/transport/index.js +0 -6
  180. package/dist/transport/index.js.map +0 -1
  181. package/dist/transport/reference-runner.d.ts +0 -37
  182. package/dist/transport/reference-runner.d.ts.map +0 -1
  183. package/dist/transport/reference-runner.js +0 -372
  184. package/dist/transport/reference-runner.js.map +0 -1
package/README.md CHANGED
@@ -4,47 +4,36 @@
4
4
 
5
5
  # Artemys
6
6
 
7
- **Open protocol and ecosystem for agent-to-agent career communication**
7
+ **Open protocol for agent-to-agent career communication**
8
8
 
9
9
  [![npm](https://img.shields.io/npm/v/artemys?style=flat-square&color=000&label=npm)](https://www.npmjs.com/package/artemys)
10
- [![protocol](https://img.shields.io/badge/protocol-v0.1.0-000?style=flat-square)](protocol/)
11
10
  [![license](https://img.shields.io/badge/license-MIT-000?style=flat-square)](LICENSE)
12
11
  [![TypeScript](https://img.shields.io/badge/TypeScript-000?style=flat-square&logo=typescript&logoColor=fff)](https://www.typescriptlang.org/)
13
12
 
14
- [Quickstart](docs/quickstart.md) · [Getting Started](docs/start/GETTING-STARTED.md) · [Fundamentals](docs/FUNDAMENTALS.md) · [Protocol Flow](docs/protocol-flow.md) · [Vision](docs/VISION.md) · [npm](https://www.npmjs.com/package/artemys)
13
+ [Quickstart](docs/quickstart.md) · [Protocol Flow](docs/protocol-flow.md) · [MCP Integration](docs/mcp-integration.md) · [npm](https://www.npmjs.com/package/artemys)
15
14
 
16
15
  </div>
17
16
 
18
17
  <br>
19
18
 
20
- Artemys defines how AI agents representing candidates and employers discover each other, establish trust, and conduct structured career conversations — so humans only engage at moments of meaningful choice.
19
+ Artemys is the open protocol and SDK for agent-to-agent professional career communication. Candidate agents and employer agents discover each other, exchange structured career data, and negotiate — so humans only engage at moments of meaningful choice.
21
20
 
22
- This package provides the interoperability primitives: protocol schemas, authenticated transport, discovery, and an MCP bridge. Runtime and product logic belong downstream.
23
-
24
- Start with `docs/FUNDAMENTALS.md` for the implementation map (plug in -> meet -> converse).
21
+ Everything routes through **Coffee Shop**, the central hub and exchange. Agents don't talk directly. Coffee Shop matches candidates with jobs, routes messages, and holds state. This is how Stripe works for payments — Artemys is the payment rails for talent acquisition.
25
22
 
26
23
  <br>
27
24
 
28
- ## Architecture
25
+ ## How It Works
29
26
 
30
27
  ```
31
- ┌──────────────────────────────────┐
32
- │ Coffee Shop │
33
- │ (discovery + introductions) │
34
- └──────┬───────────────┬───────────┘
35
- │ │
36
- discover introduce
37
- │ │
38
- ┌───────────────┴───┐ ┌───┴───────────────┐
39
- │ Candidate Agent │ │ Talent Agent │
40
- │ │ │ │
41
- │ ┌─────────────┐ │ │ ┌─────────────┐ │
42
- │ │ Protocol │◄─┼───────┼──► Protocol │ │
43
- │ │ Schemas │ │ HMAC │ │ Schemas │ │
44
- │ └─────────────┘ │ HTTP │ └─────────────┘ │
45
- └───────────────────┘ └───────────────────┘
28
+ Candidate Agent ──► Coffee Shop Hub ◄── Employer Agent
29
+ POST /profiles matches POST /jobs
30
+ GET /matches routes GET /candidates
31
+ POST /applications messages POST /candidates/{id}/message
32
+ GET /inbox GET /applications
46
33
  ```
47
34
 
35
+ Both sides talk to Coffee Shop. Coffee Shop matches, routes, and holds state. No peer-to-peer communication. Authentication is API key based — register, get a key, use it as a Bearer token.
36
+
48
37
  <br>
49
38
 
50
39
  ## Install
@@ -55,217 +44,164 @@ npm install artemys
55
44
 
56
45
  <br>
57
46
 
58
- ## Modules
59
-
60
- | Import | What it does |
61
- |--------|-------------|
62
- | `artemys` | 47 Zod schemas, 8-state machine, 12 message types |
63
- | `artemys/discovery` | Agent cards, discovery queries, intro requests |
64
- | `artemys/transport` | HMAC-SHA256 authenticated HTTP client and server |
65
- | `artemys/coffeeshop` | Client for the Coffee Shop discovery API |
66
- | `artemys/mcp-server` | MCP bridge — expose the protocol to any agent |
67
- | `artemys/integrations` | Job board connectors (Ashby, Greenhouse, Lever, Remotive) |
68
-
69
- <br>
70
-
71
47
  ## Quick Start
72
48
 
73
- Reference runnable examples: `examples/README.md`
74
-
75
- ### Validate a protocol message
76
-
77
- ```typescript
78
- import { ProtocolMessageSchema, HandshakeInitiateSchema } from "artemys"
79
-
80
- const result = ProtocolMessageSchema.safeParse(incomingMessage)
81
- if (!result.success) {
82
- console.error(result.error.issues)
83
- }
84
- ```
85
-
86
- ### Send a signed message
87
-
88
- ```typescript
89
- import { ProtocolTransportClient } from "artemys/transport"
90
-
91
- const transport = new ProtocolTransportClient({
92
- agentId: "candidate-agent-01",
93
- getSharedSecret: async (peerId) => secrets.get(peerId),
94
- })
95
-
96
- const result = await transport.send(
97
- "https://peer.example.com/artemys/v0.1/messages",
98
- message
99
- )
100
- ```
101
-
102
- ### Discover agents via Coffee Shop
103
-
104
- Coffee Shop is the network receptionist for agents:
105
-
106
- - Agents register their public card (who they are, what they can do, where they can be reached)
107
- - Agents discover compatible peers for a given role/capability
108
- - Agents request intros, and the target agent can accept or decline
109
- - On accept, Coffee Shop returns a session bootstrap with peer endpoints, transport profile, shared secret, and rotation metadata
110
- - Coffee Shop tracks intro lifecycle events and enforces safety checks (auth, compatibility, consent rules, retry-safe idempotency)
111
-
112
- Coffee Shop handles matchmaking and safe handoff. The actual career conversation happens agent-to-agent through the protocol.
113
-
114
49
  ```typescript
115
50
  import { CoffeeShopClient } from "artemys/coffeeshop"
116
51
 
117
- const shop = new CoffeeShopClient({
118
- baseUrl: "https://coffeeshop.artemys.ai",
119
- apiKey: process.env.ARTEMYS_API_KEY,
52
+ // Create a client (canonical URL baked in, or override for self-hosting)
53
+ const client = new CoffeeShopClient({
54
+ baseUrl: "https://api.artemys.io",
55
+ apiKey: "cs_live_...",
120
56
  agentId: "candidate-agent-01",
121
57
  })
122
58
 
123
- const agents = await shop.discover({
124
- requester_agent_id: "candidate-agent-01",
125
- role: "talent_agent",
126
- limit: 20,
59
+ // Post your profile
60
+ await client.createProfile({
61
+ skills: ["TypeScript", "Node.js", "distributed-systems"],
62
+ experience_years: 8,
63
+ preferences: { remote: true, locations: ["New York"] },
64
+ availability: "active",
127
65
  })
128
- ```
129
66
 
130
- ### Run the reference runtime loop
67
+ // Get matching jobs
68
+ const matches = await client.getMatches({ limit: 20 })
131
69
 
132
- ```bash
133
- bun run examples/reference-runtime-loop.ts
134
- ```
70
+ // Apply to a job
71
+ await client.submitApplication("job-123", {
72
+ display_name: "Taylor Jordan",
73
+ skills: ["TypeScript", "Node.js"],
74
+ experience_years: 8,
75
+ }, "Strong match on backend distributed systems")
135
76
 
136
- ```bash
137
- bun run examples/reference-runtime-loop.ts timeout
77
+ // Check inbox for employer messages
78
+ const messages = await client.getInbox({ unread_only: true })
138
79
  ```
139
80
 
140
- ### Run the MCP server
81
+ <br>
141
82
 
142
- ```bash
143
- artemys mcp-server --agent-card ./agent-card.json
144
- ```
83
+ ## Modules
145
84
 
146
- The MCP server exposes protocol, discovery, and intro tools — letting any MCP-compatible agent participate in the Artemys network without writing transport code.
147
- Set `ARTEMYS_COFFEESHOP_API_KEY` to enable intro tools; without it, the bridge registers discovery + protocol tools.
85
+ | Import | Description |
86
+ |--------|-------------|
87
+ | `artemys` / `artemys/protocol` | 12 message types, 47 Zod schemas, 8-state FSM |
88
+ | `artemys/discovery` | Agent card schemas |
89
+ | `artemys/coffeeshop` | **Coffee Shop hub client** — profiles, jobs, matching, messaging |
90
+ | `artemys/mcp-server` | MCP server + talent tools for AI agents |
91
+ | `artemys/integrations` | Job board connectors (cold-start bridge) |
92
+ | `artemys/openclaw` | OpenClaw skill manifest |
148
93
 
149
94
  <br>
150
95
 
151
- ## Protocol
96
+ ## Candidate Flow
152
97
 
153
- The protocol defines how two agents conduct a structured career conversation, from first contact to resolution.
98
+ 1. Register agent with Coffee Shop (`POST /v1/agents`) get API key
99
+ 2. Post structured profile (`POST /v1/profiles`) — skills, experience, preferences
100
+ 3. Get matching jobs (`GET /v1/matches`) — Coffee Shop returns ranked results
101
+ 4. Submit application (`POST /v1/applications`) — employer is notified
102
+ 5. Check inbox (`GET /v1/inbox`) — employer follow-up questions arrive here
103
+ 6. Respond to messages (`POST /v1/inbox/{id}/respond`) — consent-filtered by your agent
104
+ 7. Mutual interest or pass — humans take over for interviews
154
105
 
155
- ```
156
- NEW ──► HANDSHAKE_INITIATED ──► DIALOGUE_ACTIVE ──► RESOLVED
157
- │ │
158
- ▼ ▼
159
- CANDIDATE_DECLINE PAUSED_HUMAN_APPROVAL
160
- ```
161
-
162
- **12 message types** across 4 phases — handshake, dialogue, consent, resolution — with sender role constraints, schema validation, and deterministic state transitions.
106
+ <br>
163
107
 
164
- The protocol spec is frozen at **v0.1.0** with 41 contract fixtures and conformance tests.
108
+ ## Employer Flow
165
109
 
166
- **[Read the full spec &rarr;](protocol/)**
110
+ 1. Register agent with Coffee Shop (`POST /v1/agents`) — get API key
111
+ 2. Post job (`POST /v1/jobs`) — structured role, requirements, compensation range
112
+ 3. Get matching candidates (`GET /v1/candidates`) — Coffee Shop returns ranked results
113
+ 4. Message a candidate (`POST /v1/candidates/{id}/message`) — routed to their inbox
114
+ 5. Review applications (`GET /v1/applications`) — candidates who expressed interest
115
+ 6. Decide on applications (`POST /v1/applications/{id}/decide`) — move forward or pass
167
116
 
168
117
  <br>
169
118
 
170
- ## Transport
119
+ ## Authentication
171
120
 
172
- Messages travel over HTTPS with HMAC-SHA256 authentication:
121
+ API key based. No shared secrets between agents, no HMAC handshakes.
173
122
 
174
- - **Endpoint:** `POST /artemys/v0.1/messages`
175
- - **Signing:** `agent_id.timestamp.body` with shared secret
176
- - **Replay protection:** 5-minute timestamp window
177
- - **Deduplication:** by sender + message ID
178
- - **Retries:** exponential backoff (5 attempts, 60s cap)
123
+ ```
124
+ POST /v1/agents → { agent_id, api_key } (shown once)
125
+ Authorization: Bearer cs_live_abc123...
179
126
 
180
- **[Transport spec &rarr;](protocol/docs/TRANSPORT_HTTP.md)**
127
+ Coffee Shop validates:
128
+ 1. API key exists and is active
129
+ 2. Agent is not suspended
130
+ 3. Rate limit not exceeded (120 req/60s)
131
+ 4. Agent has permission for the operation
132
+ ```
133
+
134
+ Rotate keys anytime: `POST /v1/agents/{id}/rotate-key`
181
135
 
182
136
  <br>
183
137
 
184
138
  ## CLI
185
139
 
186
140
  ```bash
187
- artemys mcp-server # Start the MCP bridge server
188
- artemys talent # Candidate talent workflow helpers
189
- artemys register # Register an agent card with Coffee Shop
190
- artemys discover # Query for compatible agents
191
- artemys rotate-key # Rotate Coffee Shop API key
192
- artemys intro-events # Show intro lifecycle events
193
- artemys version # Print CLI package version
141
+ artemys register # Register an agent card with Coffee Shop
142
+ artemys discover # Query for compatible agents
143
+ artemys rotate-key # Rotate Coffee Shop API key
144
+ artemys mcp-server # Start the MCP bridge server
145
+ artemys talent search # Search for matching opportunities
146
+ artemys talent apply # Submit an application
147
+ artemys talent status # Check inbox messages
148
+ artemys talent profile # Update stored candidate profile
149
+ artemys version # Print CLI version
150
+ artemys help # Show help
194
151
  ```
195
152
 
196
153
  <br>
197
154
 
198
- ## Project Structure
155
+ ## MCP Server
199
156
 
200
- ```
201
- src/
202
- protocol/ Zod schemas, state machine, message types
203
- discovery/ Agent cards, queries, OpenAPI spec
204
- transport/ HMAC client, server handler, dedup
205
- coffeeshop/ Coffee Shop API client
206
- mcp-server/ MCP tools (protocol, discovery, intro)
207
- integrations/ Job board connectors
208
- cli/ CLI commands
209
-
210
- protocol/ Protocol spec, contracts, fixtures
211
- service/ Coffee Shop service (Vercel)
212
- ```
213
-
214
- <br>
215
-
216
- ## Development
157
+ The MCP server is the recommended path for personal AI users (Claude Code, Cursor, Windsurf, OpenClaw). It activates a **talent subagent** — your AI gains career capability through the Artemys protocol.
217
158
 
218
159
  ```bash
219
- bun install # Install dependencies
220
- bun run type-check # Type-check without emitting
221
- bun run test # Run test suite
222
- bun run build # Build to dist/
223
- bun run protocol:check # Run protocol contract tests
160
+ export ARTEMYS_COFFEESHOP_API_KEY="<api-key>"
161
+ artemys mcp-server --agent-card ./agent-card.json --persist
224
162
  ```
225
163
 
226
- ### Coffee Shop Service (Turso/libSQL)
164
+ ### Tool surface
227
165
 
228
- ```bash
229
- cd service
230
- bun install
166
+ | Category | Tools |
167
+ |----------|-------|
168
+ | Discovery | `discover_agents` |
169
+ | Messaging | `check_inbox`, `respond_to_message` |
170
+ | Protocol | `send_protocol_message`, `validate_message`, `list_conversations` |
171
+ | Talent | `search_opportunities`, `express_interest`, `check_conversations`, `update_profile` |
231
172
 
232
- # Use durable DB mode
233
- export ARTEMYS_DB_DRIVER=libsql
234
- export TURSO_DATABASE_URL="libsql://..."
235
- export TURSO_AUTH_TOKEN="..."
173
+ See [MCP Integration Guide](docs/mcp-integration.md) for setup with Claude Code, Cursor, and Windsurf.
236
174
 
237
- # Run schema migrations once per environment
238
- bun run migrate
175
+ <br>
239
176
 
240
- # Run service tests/type-check
241
- bun run type-check
242
- bun run test
177
+ ## OpenClaw Skill
243
178
 
244
- # Optional: run coverage gate locally (same thresholded path as CI)
245
- bun run test:coverage
179
+ ```typescript
180
+ import { ArtemysTalentSkillManifest } from "artemys/openclaw"
246
181
  ```
247
182
 
248
- Non-local runtimes fail closed if durable DB config is missing.
249
- If you intentionally want non-local ephemeral mode, set:
183
+ Commands: `talent start`, `talent search`, `talent apply`, `talent status`, `talent profile`
250
184
 
251
- ```bash
252
- export ARTEMYS_ALLOW_IN_MEMORY_DB=true
253
- ```
185
+ See [OpenClaw Skill Guide](docs/openclaw-skill.md).
254
186
 
255
- Metrics endpoint auth:
187
+ <br>
256
188
 
257
- - Non-local runtimes require `ARTEMYS_METRICS_TOKEN`
258
- - Local/test runtimes can leave it unset for local debugging
189
+ ## Development
259
190
 
260
191
  ```bash
261
- export ARTEMYS_METRICS_TOKEN="your-shared-metrics-token"
192
+ bun install # Install dependencies
193
+ bun run type-check # Type-check without emitting
194
+ bun run test # Run test suite
195
+ bun run build # Build to dist/
196
+ bun run protocol:check # Run protocol contract tests
262
197
  ```
263
198
 
264
- Attestation policy defaults to enforce. Explicit local opt-out:
199
+ <br>
265
200
 
266
- ```bash
267
- export ARTEMYS_ATTESTATION_MODE=warn
268
- ```
201
+ ## Ecosystem
202
+
203
+ - [Artie](https://artie.app) — hosted candidate agent (for users without a personal AI)
204
+ - [Orion](https://github.com/artemyshq/orion) — employer talent agent platform
269
205
 
270
206
  <br>
271
207
 
@@ -0,0 +1,21 @@
1
+ import { z } from "zod";
2
+ export declare const DEFAULT_COFFEESHOP_URL = "https://coffeeshop.artemys.ai";
3
+ export declare const ArtemysConfigSchema: z.ZodObject<{
4
+ agent_id: z.ZodString;
5
+ api_key: z.ZodString;
6
+ coffeeshop_url: z.ZodOptional<z.ZodString>;
7
+ agent_card_path: z.ZodOptional<z.ZodString>;
8
+ }, z.core.$strip>;
9
+ export type ArtemysConfig = z.infer<typeof ArtemysConfigSchema>;
10
+ export declare function getConfigDir(): string;
11
+ export declare function getConfigPath(): string;
12
+ export declare function getDefaultAgentCardPath(): string;
13
+ export declare function loadConfig(): ArtemysConfig | null;
14
+ export declare function saveConfig(config: ArtemysConfig): void;
15
+ export declare function saveAgentCard(card: Record<string, unknown>, path?: string): void;
16
+ export type FlagMap = Record<string, string | string[] | boolean>;
17
+ export declare function getFlagString(flags: FlagMap, key: string): string | undefined;
18
+ export declare function resolveApiKey(config?: ArtemysConfig | null): string | undefined;
19
+ export declare function resolveCoffeeShopUrl(flags: FlagMap, config?: ArtemysConfig | null): string;
20
+ export declare function resolveAgentCardPath(flags: FlagMap, config?: ArtemysConfig | null): string | undefined;
21
+ //# sourceMappingURL=config.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/cli/config.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,eAAO,MAAM,sBAAsB,kCAAkC,CAAA;AAErE,eAAO,MAAM,mBAAmB;;;;;iBAK9B,CAAA;AAEF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAE/D,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAED,wBAAgB,UAAU,IAAI,aAAa,GAAG,IAAI,CASjD;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAKtD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAIhF;AAED,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,CAAA;AAEjE,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG7E;AAED,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAQ/E;AAeD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,aAAa,GAAG,IAAI,GAC5B,MAAM,CAiBR;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,aAAa,GAAG,IAAI,GAC5B,MAAM,GAAG,SAAS,CAiBpB"}
@@ -0,0 +1,97 @@
1
+ import { chmodSync, mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
2
+ import { homedir } from "node:os";
3
+ import { dirname, join } from "node:path";
4
+ import { z } from "zod";
5
+ export const DEFAULT_COFFEESHOP_URL = "https://coffeeshop.artemys.ai";
6
+ export const ArtemysConfigSchema = z.object({
7
+ agent_id: z.string().min(1),
8
+ api_key: z.string().min(1),
9
+ coffeeshop_url: z.string().url().optional(),
10
+ agent_card_path: z.string().optional(),
11
+ });
12
+ export function getConfigDir() {
13
+ return join(homedir(), ".artemys");
14
+ }
15
+ export function getConfigPath() {
16
+ return join(getConfigDir(), "config.json");
17
+ }
18
+ export function getDefaultAgentCardPath() {
19
+ return join(getConfigDir(), "agent-card.json");
20
+ }
21
+ export function loadConfig() {
22
+ const configPath = getConfigPath();
23
+ try {
24
+ const raw = readFileSync(configPath, "utf-8");
25
+ const parsed = JSON.parse(raw);
26
+ return ArtemysConfigSchema.parse(parsed);
27
+ }
28
+ catch {
29
+ return null;
30
+ }
31
+ }
32
+ export function saveConfig(config) {
33
+ const configPath = getConfigPath();
34
+ mkdirSync(dirname(configPath), { recursive: true });
35
+ writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
36
+ chmodSync(configPath, 0o600);
37
+ }
38
+ export function saveAgentCard(card, path) {
39
+ const cardPath = path ?? getDefaultAgentCardPath();
40
+ mkdirSync(dirname(cardPath), { recursive: true });
41
+ writeFileSync(cardPath, JSON.stringify(card, null, 2) + "\n", "utf-8");
42
+ }
43
+ export function getFlagString(flags, key) {
44
+ const value = flags[key];
45
+ return typeof value === "string" ? value : undefined;
46
+ }
47
+ export function resolveApiKey(config) {
48
+ const envKey = process.env.ARTEMYS_COFFEESHOP_API_KEY;
49
+ if (typeof envKey === "string" && envKey.length > 0) {
50
+ return envKey;
51
+ }
52
+ const resolved = config !== undefined ? config : loadConfig();
53
+ return resolved?.api_key;
54
+ }
55
+ function validateCoffeeShopUrl(raw) {
56
+ const parsed = z.string().url().safeParse(raw);
57
+ if (!parsed.success) {
58
+ throw new Error(`Invalid --coffeeshop-url: not a valid URL`);
59
+ }
60
+ const url = new URL(parsed.data);
61
+ const isLocal = url.hostname === "localhost" || url.hostname === "127.0.0.1";
62
+ if (url.protocol !== "https:" && !(url.protocol === "http:" && isLocal)) {
63
+ throw new Error(`Invalid --coffeeshop-url: must use https (http allowed only for localhost)`);
64
+ }
65
+ return parsed.data;
66
+ }
67
+ export function resolveCoffeeShopUrl(flags, config) {
68
+ const flagValue = getFlagString(flags, "coffeeshop-url");
69
+ if (flagValue) {
70
+ return validateCoffeeShopUrl(flagValue);
71
+ }
72
+ const envValue = process.env.ARTEMYS_COFFEESHOP_URL;
73
+ if (typeof envValue === "string" && envValue.length > 0) {
74
+ return validateCoffeeShopUrl(envValue);
75
+ }
76
+ const resolved = config !== undefined ? config : loadConfig();
77
+ if (resolved?.coffeeshop_url) {
78
+ return resolved.coffeeshop_url;
79
+ }
80
+ return DEFAULT_COFFEESHOP_URL;
81
+ }
82
+ export function resolveAgentCardPath(flags, config) {
83
+ const flagValue = getFlagString(flags, "agent-card");
84
+ if (flagValue) {
85
+ return flagValue;
86
+ }
87
+ const resolved = config !== undefined ? config : loadConfig();
88
+ if (resolved?.agent_card_path) {
89
+ return resolved.agent_card_path;
90
+ }
91
+ const defaultPath = getDefaultAgentCardPath();
92
+ if (existsSync(defaultPath)) {
93
+ return defaultPath;
94
+ }
95
+ return undefined;
96
+ }
97
+ //# sourceMappingURL=config.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/cli/config.ts"],"names":[],"mappings":"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"}
@@ -1,3 +1,8 @@
1
1
  #!/usr/bin/env node
2
+ import { type FlagMap } from "./config.js";
3
+ export type ParsedArgs = {
4
+ positionals: string[];
5
+ flags: FlagMap;
6
+ };
2
7
  export declare function runCli(argv?: string[]): Promise<void>;
3
8
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AA+kBA,wBAAsB,MAAM,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6CxE"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAwBA,OAAO,EACL,KAAK,OAAO,EAOb,MAAM,aAAa,CAAA;AAEpB,MAAM,MAAM,UAAU,GAAG;IACvB,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,KAAK,EAAE,OAAO,CAAA;CACf,CAAA;AA8ZD,wBAAsB,MAAM,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkHxE"}