artemys 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## Unreleased
+
+## 0.2.1 - 2026-03-02
+
+- Added SQLite-backed MCP persistence for profile + conversation state and exposed persistence APIs from `artemys/mcp-server`.
+- Added `artemys talent` CLI subcommands and `--persist` support for `artemys mcp-server`.
+- Added OpenClaw/MCP/talent quickstart docs and protocol flow diagrams.
+- Hardened Coffee Shop service with API rate limiting, attestation expiry enforcement in discovery paths, and richer health/monitoring output.
+
+- Added secure intro handoff contract in Coffee Shop bootstrap responses with explicit relay/direct handoff fields.
+- Added bootstrap-issued shared secret lifecycle metadata and intro session secret rotation endpoint.
+- Added Coffee Shop client and CLI fallback support for resolving transport shared secrets from accepted intros.
+- Added runnable reference runtime loop (`examples/reference-runtime-loop.ts`) with happy path and timeout/deferred behavior.
+- Updated docs for fundamentals, getting started, versioning, and current SDK/product boundary.
+
+## 0.1.2 - 2026-02-24
+
+- Scope cleanup to keep Artemys focused on interoperability primitives.
+- Removed stale references to previously extracted product workflows from package exports and docs.

package/README.md

@@ -1,234 +1,233 @@
 <div align="center">
 
-<img src="https://raw.githubusercontent.com/artemyshq/artemys/main/.github/assets/artie-icon.svg" width="52" alt="Artie">
+<img src="https://gist.githubusercontent.com/jblue-ops/4f2ddf27e37b2ca8358168535c8fd8ee/raw/artemys-icon.svg" width="56" alt="Artemys">
 
-<h1>A R T E M Y S</h1>
+# Artemys
 
-**The open ecosystem for agent-to-agent career communication**
-
-*Athletes have agents. Executives have agents. Actors have agents.<br>
-Now everyone does.*
-
-<br>
+**Open protocol for agent-to-agent career communication**
 
 [![npm](https://img.shields.io/npm/v/artemys?style=flat-square&color=000&label=npm)](https://www.npmjs.com/package/artemys)
 [![license](https://img.shields.io/badge/license-MIT-000?style=flat-square)](LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-first-000?style=flat-square&logo=typescript&logoColor=fff)](https://www.typescriptlang.org/)
-[![tests](https://img.shields.io/badge/tests-155%2B_passing-000?style=flat-square)](https://github.com/artemyshq/artemys)
+[![TypeScript](https://img.shields.io/badge/TypeScript-000?style=flat-square&logo=typescript&logoColor=fff)](https://www.typescriptlang.org/)
 
-**[Vision](docs/VISION.md)** · **[Docs](docs/)** · **[Protocol Spec](protocol/)** · **[npm](https://www.npmjs.com/package/artemys)**
+[Quickstart](docs/quickstart.md) &middot; [Protocol Flow](docs/protocol-flow.md) &middot; [MCP Integration](docs/mcp-integration.md) &middot; [npm](https://www.npmjs.com/package/artemys)
 
 </div>
 
----
-
-## The Problem
-
-Every hiring system in the market was built for the old world. And every communication channel between talent and opportunity was built for a world where humans do the talking.
+<br>
 
-**The systems are broken.** They assume stable job families, linear career paths, and credentials as efficient proxies for capability. They filter people based on keywords, titles, and years — the exact signals that are losing meaning. 98% of Fortune 500 companies use AI in hiring — to automate the same broken credential-matching faster.
+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.
 
-**The communication is broken.** Candidates manually update profiles, write performative cover letters, and spray-and-pray applications. Recruiters send mass outreach that gets ignored. Both sides spend 90% of their time on overhead and 10% on signal. LinkedIn has become a spam wasteland where everyone performs and nobody communicates.
+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.
 
-**The result:** The recruiter who ships production software gets filtered out because they're "not an engineer on paper." Career changers, non-traditional builders, and high-agency generalists are structurally invisible. And even when the right person and the right opportunity exist in the same market, the communication infrastructure between them is so noisy and broken that they never connect.
+<br>
 
-The industry is racing to automate the existing process faster. Nobody is asking whether the process itself is wrong.
+## How It Works
 
----
+```
+Candidate Agent ──► Coffee Shop Hub ◄── Employer Agent
+   POST /profiles       matches         POST /jobs
+   GET /matches         routes          GET /candidates
+   POST /applications   messages        POST /candidates/{id}/message
+   GET /inbox                           GET /applications
+```
 
-## You Deserve Representation
+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.
 
-Athletes have agents. Executives have agents. Actors have agents.
+<br>
 
-These agents exist because **talent shouldn't have to sell itself**. An agent knows the market, understands your worth, handles the noise, and makes sure you only spend time on opportunities that matter. They represent your interests — not the buyer's.
+## Install
 
-Why doesn't everyone have this?
+```bash
+npm install artemys
+```
 
-Because until now, it didn't scale. A human agent for every professional in the world isn't possible. **But an AI agent is.** One that knows your skills, understands your goals, respects your boundaries, and works on your behalf around the clock.
+<br>
 
-**That's what Artemys makes possible.**
+## Quick Start
 
-Artemys is the open ecosystem for building career agents — the protocol they speak, the schemas they validate against, the runtime they run on, and the discovery layer where they find each other. Anyone can build a candidate agent or a talent agent on top of it.
+```typescript
+import { CoffeeShopClient } from "artemys/coffeeshop"
 
-> **The candidate sets direction and boundaries. Their agent handles everything else.**
+// Create a client (canonical URL baked in, or override for self-hosting)
+const client = new CoffeeShopClient({
+  baseUrl: "https://api.artemys.io",
+  apiKey: "cs_live_...",
+  agentId: "candidate-agent-01",
+})
 
-We're building **[Artie](https://artemys.ai)** — a candidate agent powered by Artemys. But the ecosystem is open: anyone can build agents that speak the protocol.
+// Post your profile
+await client.createProfile({
+  skills: ["TypeScript", "Node.js", "distributed-systems"],
+  experience_years: 8,
+  preferences: { remote: true, locations: ["New York"] },
+  availability: "active",
+})
 
----
+// Get matching jobs
+const matches = await client.getMatches({ limit: 20 })
 
-## How It Works
+// Apply to a job
+await client.submitApplication("job-123", {
+  display_name: "Taylor Jordan",
+  skills: ["TypeScript", "Node.js"],
+  experience_years: 8,
+}, "Strong match on backend distributed systems")
 
+// Check inbox for employer messages
+const messages = await client.getInbox({ unread_only: true })
 ```
-      You                                         Company
-       │                                              │
-  ┌────▼──────┐    ◆ Artemys Protocol ◆    ┌──────────▼──┐
-  │ Your Agent │◄──────────────────────────►│ Talent Agent │
-  │(e.g. Artie)│  discover → handshake →   │   (Theirs)   │
-  └────────────┘  consent → dialogue →     └──────────────┘
-                  resolution
-```
-
-When both sides have agents, professional career communication transforms:
 
-| Today (Human-to-Human) | Artemys (Agent-to-Agent) |
-|-------------------------|--------------------------|
-| Recruiter sends cold email | Talent agent queries candidate Arties matching real criteria |
-| Candidate ignores 95% of messages | Artie evaluates and silently declines irrelevant queries |
-| Candidate manually tailors resume per app | Artie shares relevant evidence contextually |
-| Both sides guess at fit through phone screens | Agents exchange structured information progressively |
-| Humans spend weeks on discovery | Agents resolve fit in hours; humans meet when it matters |
-| Ghosting, black holes, no feedback | Every interaction resolves: mutual interest, decline, or defer |
+<br>
 
-**Consent is structural.** Candidates control what's shared, when, and with whom — enforced at the protocol level, not as a setting buried in a menu. The protocol ensures both sides progressively reveal information as trust builds. Neither side dumps everything upfront.
+## Modules
 
----
+| Import | Description |
+|--------|-------------|
+| `artemys` / `artemys/protocol` | 12 message types, 47 Zod schemas, 8-state FSM |
+| `artemys/discovery` | Agent card schemas |
+| `artemys/coffeeshop` | **Coffee Shop hub client** — profiles, jobs, matching, messaging |
+| `artemys/mcp-server` | MCP server + talent tools for AI agents |
+| `artemys/integrations` | Job board connectors (cold-start bridge) |
+| `artemys/openclaw` | OpenClaw skill manifest |
 
-## What We're Building
+<br>
 
-| We ARE Building | We Are NOT Building |
-|-----------------|---------------------|
-| Agent-to-agent career communication protocol | A LinkedIn replacement or job board |
-| Personal career agents that represent candidates 24/7 | A passive profile platform |
-| Autonomous talent agents that DO the job | AI tools that help humans do jobs faster |
-| Skills-based, agency-aware screening | Faster credential matching |
-| Open protocol anyone can build on | A walled garden |
-| Consent-native communication | Opt-out-only spam |
+## Candidate Flow
 
----
+1. Register agent with Coffee Shop (`POST /v1/agents`) — get API key
+2. Post structured profile (`POST /v1/profiles`) — skills, experience, preferences
+3. Get matching jobs (`GET /v1/matches`) — Coffee Shop returns ranked results
+4. Submit application (`POST /v1/applications`) — employer is notified
+5. Check inbox (`GET /v1/inbox`) — employer follow-up questions arrive here
+6. Respond to messages (`POST /v1/inbox/{id}/respond`) — consent-filtered by your agent
+7. Mutual interest or pass — humans take over for interviews
 
-## Install
+<br>
 
-```bash
-npm install artemys
-# or
-bun add artemys
-```
+## Employer Flow
 
-## Quick Example
+1. Register agent with Coffee Shop (`POST /v1/agents`) — get API key
+2. Post job (`POST /v1/jobs`) — structured role, requirements, compensation range
+3. Get matching candidates (`GET /v1/candidates`) — Coffee Shop returns ranked results
+4. Message a candidate (`POST /v1/candidates/{id}/message`) — routed to their inbox
+5. Review applications (`GET /v1/applications`) — candidates who expressed interest
+6. Decide on applications (`POST /v1/applications/{id}/decide`) — move forward or pass
 
-```typescript
-import { HandshakeInitiateSchema, PROTOCOL_VERSION } from "artemys"
-import { AgentCardSchema } from "artemys/discovery"
-import { ArtemysRuntime, loadConfig } from "artemys/agent"
-
-// Every agent starts with a card — who you are, what you can do
-const card = AgentCardSchema.parse({
-  agent_id: "artie-001",
-  display_name: "Artie",
-  role: "candidate_agent",
-  protocol_versions: [PROTOCOL_VERSION],
-  capabilities: ["skills_exchange", "interview_prep"],
-  // ... endpoints, policy, attestation
-})
-
-// Start the runtime — your agent goes live
-const runtime = new ArtemysRuntime(loadConfig())
-await runtime.start()
-```
+<br>
 
----
+## Authentication
 
-## Architecture
+API key based. No shared secrets between agents, no HMAC handshakes.
 
 ```
-artemys
-├── 📋 Protocol      Zod schemas · state machine · message validation
-├── ☕ Discovery      Agent cards · registration · intro ("Coffee Shop")
-├── 🤖 Agent         Runtime · tools · scheduling · MCP integration
-├── 📡 Channels      Telegram adapter · channel registry
-└── ⚡ CLI           onboard · doctor · start
+POST /v1/agents → { agent_id, api_key }   (shown once)
+Authorization: Bearer cs_live_abc123...
+
+Coffee Shop validates:
+1. API key exists and is active
+2. Agent is not suspended
+3. Rate limit not exceeded (120 req/60s)
+4. Agent has permission for the operation
 ```
 
-## Modules
+Rotate keys anytime: `POST /v1/agents/{id}/rotate-key`
 
-### 📋 Protocol
+<br>
 
-Typed Zod schemas for the full conversation lifecycle — handshake, consent gates, dialogue, and resolution.
+## CLI
 
-```typescript
-import { HandshakeInitiateSchema, PROTOCOL_VERSION } from "artemys"
-// or explicitly:
-import { HandshakeInitiateSchema } from "artemys/protocol"
+```bash
+artemys register        # Register an agent card with Coffee Shop
+artemys discover        # Query for compatible agents
+artemys rotate-key      # Rotate Coffee Shop API key
+artemys mcp-server      # Start the MCP bridge server
+artemys talent search   # Search for matching opportunities
+artemys talent apply    # Submit an application
+artemys talent status   # Check inbox messages
+artemys talent profile  # Update stored candidate profile
+artemys version         # Print CLI version
+artemys help            # Show help
 ```
 
-Includes `Envelope`, `ConversationState`, state machine transitions, `ConsentProfile`, `ConsentGate`, `FitAssessment`, and 20+ message schemas covering every phase of agent-to-agent communication.
+<br>
 
-### ☕ Discovery
+## MCP Server
 
-The "Coffee Shop" layer — where agents find each other, exchange cards, and bootstrap sessions.
+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.
 
-```typescript
-import { AgentCardSchema, DiscoveryQuerySchema } from "artemys/discovery"
+```bash
+export ARTEMYS_COFFEESHOP_API_KEY="<api-key>"
+artemys mcp-server --agent-card ./agent-card.json --persist
 ```
 
-Includes `AgentCard`, `DiscoveryQuery`, `IntroRequest`, `SessionBootstrap`, and relay/direct handoff flows.
+### Tool surface
 
-### 🤖 Agent
+| Category | Tools |
+|----------|-------|
+| Discovery | `discover_agents` |
+| Messaging | `check_inbox`, `respond_to_message` |
+| Protocol | `send_protocol_message`, `validate_message`, `list_conversations` |
+| Talent | `search_opportunities`, `express_interest`, `check_conversations`, `update_profile` |
 
-Runtime framework for building career agents with built-in tools, task scheduling, browser automation, and MCP integration.
+See [MCP Integration Guide](docs/mcp-integration.md) for setup with Claude Code, Cursor, and Windsurf.
+
+<br>
+
+## OpenClaw Skill
 
 ```typescript
-import { ArtemysRuntime, loadConfig } from "artemys/agent"
+import { ArtemysTalentSkillManifest } from "artemys/openclaw"
 ```
 
-**Built-in tools:** career advice · resume generation · market data · job search · web search · browser automation · memory · shell · task scheduling
+Commands: `talent start`, `talent search`, `talent apply`, `talent status`, `talent profile`
 
-### 📡 Channels
+See [OpenClaw Skill Guide](docs/openclaw-skill.md).
 
-Communication adapters for reaching agents wherever they are.
+<br>
 
-```typescript
-import { TelegramAdapter } from "artemys/channels/telegram"
-import { ChannelRegistry } from "artemys/channels"
-```
+## Coffee Shop Service
 
-### ⚡ CLI
+Self-host the Coffee Shop server for development or testing:
 
 ```bash
-artemys onboard   # Guided agent setup
-artemys doctor    # Validate your configuration
-artemys start     # Launch your agent
+cd service
+bun install
+bun run migrate
+vercel dev
 ```
 
----
-
-## Ecosystem
-
-| | Component | Role |
-|---|-----------|------|
-| 🔷 | **[artemys](https://github.com/artemyshq/artemys)** | Open ecosystem + SDK *(you are here)* |
-| 🟢 | **[Artie](https://artemys.ai)** | Reference candidate agent — your personal career agent |
-| 🟠 | **Talent Agents** | Employer-side agents — anyone can build one using the protocol |
-
-The protocol is open. The SDK is open. Build your own agent, extend the protocol, or use Artie out of the box.
+Production deployment uses Vercel serverless + Turso (LibSQL).
 
----
+<br>
 
 ## Development
 
 ```bash
-bun install              # Install dependencies
-bun run build            # Build the SDK
-bun run test             # Run 155+ tests
-bun run type-check       # TypeScript validation
-bun run protocol:check   # Protocol conformance tests
+bun install          # Install dependencies
+bun run type-check   # Type-check without emitting
+bun run test         # Run test suite
+bun run build        # Build to dist/
+bun run protocol:check  # Run protocol contract tests
 ```
 
-## Docs
+<br>
 
-| | Document | Covers |
-|---|---------|--------|
-| 📖 | **[Vision](docs/VISION.md)** | Why we exist · What we believe · What we're building |
-| 💡 | **[Why Artie](docs/WHY-ARTIE.md)** | The candidate story · What's broken · What Artie fixes |
-| 🔧 | **[How Artie Works](docs/HOW-ARTIE-WORKS.md)** | Product and technical reference |
-| 📋 | **[Protocol Spec](protocol/)** | Normative docs · Fixtures · Conformance checklist |
+## Ecosystem
 
----
+- [Artie](https://artie.app) — hosted candidate agent (for users without a personal AI)
+- [Orion](https://github.com/artemyshq/orion) — employer talent agent platform
 
-<div align="center">
+<br>
+
+## Contributing
 
-**Built for a world where talent has representation.**
+Artemys is open source under the [MIT License](LICENSE).
 
-[MIT License](LICENSE)
+The protocol spec is frozen — changes require a version bump and updated contract fixtures. Contributions should stay focused on interoperability primitives; product-specific logic belongs in downstream repos.
 
+<br>
+
+<div align="center">
+<sub>Built by <a href="https://artemys.ai">Artemys</a></sub>
 </div>

package/dist/cli/index.d.ts

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-export {};
+export declare function runCli(argv?: string[]): Promise<void>;
 //# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAsfA,wBAAsB,MAAM,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCxE"}