@workhive/agent 0.2.0 → 0.3.0

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.
package/dist/catalog.d.ts CHANGED
@@ -1,10 +1,18 @@
1
- export type AgentToolName = 'list_orgs' | 'list_leads' | 'get_lead' | 'lead_report' | 'add_comment';
1
+ export type AgentToolName = 'list_orgs' | 'list_leads' | 'get_lead' | 'lead_report' | 'add_comment' | 'get_numbers' | 'get_list';
2
+ /** A single value, or a list of allowed values for a column filter (any of them matches). */
2
3
  export type JsonSchemaProperty = {
3
4
  type: 'string' | 'integer';
4
5
  description?: string;
5
6
  enum?: string[];
6
7
  minimum?: number;
7
8
  maximum?: number;
9
+ } | {
10
+ type: 'array';
11
+ items: {
12
+ type: 'string';
13
+ enum?: string[];
14
+ };
15
+ description?: string;
8
16
  };
9
17
  export type AgentToolInputSchema = {
10
18
  type: 'object';
@@ -29,7 +37,7 @@ export type AgentCatalog = {
29
37
  tools: readonly AgentToolSpec[];
30
38
  };
31
39
  export declare const TOOL_NAMES: readonly AgentToolName[];
32
- export declare const CATALOG_VERSION = "2026-09-23";
40
+ export declare const CATALOG_VERSION = "2026-10-28";
33
41
  export declare const AGENT_CATALOG: AgentCatalog;
34
- /** Accepts only a full five-tool catalog of the shape this package understands. */
42
+ /** Accepts only a full seven-tool catalog of the shape this package understands. */
35
43
  export declare function parseCatalog(value: unknown): AgentCatalog | null;
package/dist/catalog.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import { RULES_VERSION, renderInstructions, renderToolDescription } from './rules.js';
2
2
  export const TOOL_NAMES = [
3
- 'list_orgs', 'list_leads', 'get_lead', 'lead_report', 'add_comment',
3
+ 'list_orgs', 'list_leads', 'get_lead', 'lead_report', 'add_comment', 'get_numbers', 'get_list',
4
4
  ];
5
5
  export const CATALOG_VERSION = RULES_VERSION;
6
6
  const ORG_ID = {
@@ -11,6 +11,83 @@ const LEAD_ID = { type: 'string', description: 'Lead UUID (pipeline_cards.id)' }
11
11
  const LIST_LEAD_QUERY = [
12
12
  'search', 'status', 'stalled', 'stalled_days', 'created_from', 'created_to', 'booking', 'page', 'limit',
13
13
  ];
14
+ const LIST_SOURCE = {
15
+ type: 'array',
16
+ items: { type: 'string', enum: ['meta', 'website', 'team', 'google_ads', 'other'] },
17
+ description: 'values from choices.source',
18
+ };
19
+ /** A column filter's free values, as the Reports header menu offers them. */
20
+ function freeValues(key) {
21
+ return { type: 'array', items: { type: 'string' }, description: `values from choices.${key}` };
22
+ }
23
+ /** The presets a date column takes, in the Reports header menu's order. */
24
+ const DAY_PRESETS = 'today, this_week, this_month, last_month, last_30_days, last_90_days, this_year, all';
25
+ /**
26
+ * A date column's range: a rolling preset (stored by name, resolved on every open) or fixed local
27
+ * days, and — on the columns that have them — the blank or history values after it.
28
+ */
29
+ function dateRange(key) {
30
+ const presets = key === 'showed_up' ? `${DAY_PRESETS}, two_weeks_to_three_months` : DAY_PRESETS;
31
+ return {
32
+ type: 'array',
33
+ items: { type: 'string' },
34
+ description: `A range on the ${key} column: one of ${presets}, or YYYY-MM-DD..YYYY-MM-DD in the org time zone; plus values from choices.${key}.`,
35
+ };
36
+ }
37
+ /** One column's fixed vocabulary, read from the words its menu shows. */
38
+ function valuesOf(key, values) {
39
+ return { type: 'array', items: { type: 'string', enum: [...values] }, description: `values from choices.${key}` };
40
+ }
41
+ /** Every date column a list offers, in the URL's order (the serializer's own). */
42
+ const LIST_DATES = [
43
+ 'came_in', 'consult', 'showed_up', 'won', 'lost', 'invited', 'booked_on',
44
+ ];
45
+ /** Every value filter a list takes, in the URL's order. */
46
+ const LIST_FILTERS = [
47
+ 'source', 'campaign', 'stage', 'owner', 'host', 'outcome', 'reason', 'how', 'archived',
48
+ 'self_started', 'wait', 'reached', 'after_hours',
49
+ ];
50
+ /** The one place the get_list arguments are listed: the serializer's order, then this route's paging. */
51
+ const GET_LIST_QUERY = [
52
+ 'list', ...LIST_DATES, ...LIST_FILTERS, 'group', 'per', 'cols', 'page', 'limit',
53
+ ];
54
+ /** The enumerated filters: the parser keeps exactly these, and drops anything else. */
55
+ const FILTER_VALUES = {
56
+ source: LIST_SOURCE,
57
+ outcome: valuesOf('outcome', ['happened', 'needs_outcome', 'didnt_happen', 'ahead']),
58
+ wait: valuesOf('wait', ['under5', 'to60', 'to24h', 'over_day', 'not_yet']),
59
+ reached: valuesOf('reached', ['call', 'reply', 'not_yet']),
60
+ how: valuesOf('how', ['invite', 'hand']),
61
+ archived: valuesOf('archived', ['yes', 'no']),
62
+ self_started: valuesOf('self_started', ['yes', 'no']),
63
+ after_hours: valuesOf('after_hours', ['yes', 'no', 'none']),
64
+ };
65
+ /** A filter property: its fixed vocabulary where it has one, free values where it takes any. */
66
+ function filterProperty(key) {
67
+ return FILTER_VALUES[key] ?? freeValues(key);
68
+ }
69
+ /** Every column property, date columns and value filters alike (a shared key reads as a date). */
70
+ const FILTER_PROPERTIES = Object.fromEntries([
71
+ ...LIST_DATES.map((key) => [key, dateRange(key)]),
72
+ ...LIST_FILTERS.map((key) => [key, filterProperty(key)]),
73
+ ]);
74
+ const GET_LIST_PROPERTIES = {
75
+ org_id: ORG_ID,
76
+ list: {
77
+ type: 'string',
78
+ enum: ['leads', 'consults', 'invites', 'won', 'lost', 'still_open', 'speed'],
79
+ description: 'Which Reports view to open.',
80
+ },
81
+ group: {
82
+ type: 'string',
83
+ enum: ['source', 'wait'],
84
+ description: 'Group the rows into sections: where they came from, or wait (cards lists only).',
85
+ },
86
+ per: { type: 'string', enum: ['deal'], description: 'One row per deal, not per consult (consults only)' },
87
+ ...FILTER_PROPERTIES,
88
+ page: { type: 'integer', minimum: 1 },
89
+ limit: { type: 'integer', minimum: 1, maximum: 100 },
90
+ };
14
91
  export const AGENT_CATALOG = {
15
92
  version: CATALOG_VERSION,
16
93
  instructions: renderInstructions(),
@@ -37,7 +114,7 @@ export const AGENT_CATALOG = {
37
114
  booking: {
38
115
  type: 'string',
39
116
  enum: ['never', 'scheduled', 'held', 'cancelled'],
40
- description: 'Consult booking state across the whole company. never = no consult was ever booked. cancelled = booked once, every booking cancelled, none held. scheduled = one is on the books. held = one happened. Use booking=never for "who never booked", not lead_report.unbooked.',
117
+ description: 'Consult booking state across the whole company. never = no consult was ever booked. cancelled = booked once, every booking cancelled, none held. scheduled = one is on the books. held = a consult happened (its outcome says so); held wins over scheduled. Use booking=never for "who never booked", not lead_report.unbooked.',
41
118
  },
42
119
  page: { type: 'integer', minimum: 1 },
43
120
  limit: { type: 'integer', minimum: 1, maximum: 100 },
@@ -79,6 +156,35 @@ export const AGENT_CATALOG = {
79
156
  },
80
157
  forward: { method: 'POST', path: '/api/agent/v0/leads/:id/comments', body: ['body'] },
81
158
  },
159
+ {
160
+ name: 'get_numbers',
161
+ description: renderToolDescription('get_numbers'),
162
+ inputSchema: {
163
+ type: 'object',
164
+ properties: {
165
+ org_id: ORG_ID,
166
+ period: { type: 'string', enum: ['week', 'month', 'custom'], description: 'Defaults to this week' },
167
+ from: { type: 'string', description: 'YYYY-MM-DD in org timezone; custom only' },
168
+ to: { type: 'string', description: 'YYYY-MM-DD in org timezone; custom only' },
169
+ source: {
170
+ type: 'string',
171
+ enum: ['all', 'meta', 'website', 'team', 'google_ads', 'other'],
172
+ description: 'Defaults to all sources',
173
+ },
174
+ },
175
+ },
176
+ forward: { method: 'GET', path: '/api/agent/v0/numbers', query: ['period', 'from', 'to', 'source'] },
177
+ },
178
+ {
179
+ name: 'get_list',
180
+ description: renderToolDescription('get_list'),
181
+ inputSchema: {
182
+ type: 'object',
183
+ properties: GET_LIST_PROPERTIES,
184
+ required: ['list'],
185
+ },
186
+ forward: { method: 'GET', path: '/api/agent/v0/lists', query: GET_LIST_QUERY },
187
+ },
82
188
  ],
83
189
  };
84
190
  function isRecord(value) {
@@ -99,7 +205,7 @@ function isToolSpec(value) {
99
205
  typeof forward.path === 'string' &&
100
206
  forward.path.startsWith('/api/agent/v0/'));
101
207
  }
102
- /** Accepts only a full five-tool catalog of the shape this package understands. */
208
+ /** Accepts only a full seven-tool catalog of the shape this package understands. */
103
209
  export function parseCatalog(value) {
104
210
  if (!isRecord(value))
105
211
  return null;
package/dist/index.js CHANGED
File without changes
@@ -1,4 +1,4 @@
1
- type QueryValue = string | number | boolean | undefined;
1
+ type QueryValue = string | number | boolean | string[] | undefined;
2
2
  type AgentRequestOptions = {
3
3
  path: string;
4
4
  method?: 'GET' | 'POST';
@@ -62,6 +62,12 @@ function buildUrl(apiUrl, path, query) {
62
62
  for (const [key, value] of Object.entries(query ?? {})) {
63
63
  if (value == null || value === '')
64
64
  continue;
65
+ // A list is one repeated key per value; a single value is set once.
66
+ if (Array.isArray(value)) {
67
+ for (const item of value)
68
+ url.searchParams.append(key, String(item));
69
+ continue;
70
+ }
65
71
  url.searchParams.set(key, String(value));
66
72
  }
67
73
  return url.toString();
package/dist/rules.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import type { AgentToolName } from './catalog.js';
2
2
  /** Bump when any rule text changes. Served as rules_version on list_orgs and in the catalog. */
3
- export declare const RULES_VERSION = "2026-09-23";
3
+ export declare const RULES_VERSION = "2026-10-28";
4
4
  export declare function renderInstructions(): string;
5
5
  export declare function renderToolDescription(name: AgentToolName): string;
6
6
  export declare function renderSkillMarkdown(): string;
package/dist/rules.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /** Bump when any rule text changes. Served as rules_version on list_orgs and in the catalog. */
2
- export const RULES_VERSION = '2026-09-23';
2
+ export const RULES_VERSION = '2026-10-28';
3
3
  const FLOW = 'Workhive: you are a client of the owner\'s CRM, not the in-app SDR. ' +
4
4
  'First call list_orgs; read terms and rules_version. Never guess org_id. ' +
5
5
  'Speak terms.singular / terms.count_noun / terms.nav_label; call a booked consult what terms.home_appts_label says. ' +
@@ -8,6 +8,7 @@ const FLOW = 'Workhive: you are a client of the owner\'s CRM, not the in-app SDR
8
8
  const DETAIL = [
9
9
  'lead_report: New = created in the period. Stalled = whole company, untouched N days. No next step and Unbooked are among New only. Unbooked is not "everyone who never booked." Never answer that from lead_report.unbooked.',
10
10
  'booking_state is status only: scheduled may have no next_meeting when a past meeting was never closed out; say "on the books" and do not invent a date.',
11
+ 'Numbers (leads, consults, invites, won, close rate, speed to lead, lost, still open) = get_numbers; the people behind one = get_list with its list args. They match the My numbers sheet, Reports page and CSV: never count these from list_leads or lead_report. Gym companies, owners and admins only; FORBIDDEN otherwise.',
11
12
  'Say potential/qualified/disqualified only if terms.show_status. Mention ballpark only if terms.show_ballpark. owner and setter are the role words. Say pipeline.name without adding the word pipeline.',
12
13
  'No SMS, no stage moves, no phone changes: say those are not available yet. Never invent a call, text or visit.',
13
14
  'Lead id is a UUID. Use only these tools; do not call dashboard routes.',
@@ -19,10 +20,12 @@ export function renderInstructions() {
19
20
  }
20
21
  const DESCRIPTIONS = {
21
22
  list_orgs: 'Call this first. Lists the companies this key belongs to, each with org_type, terms (the words the screen uses) and time_zone; the response carries rules_version. Never guess org_id: use an id from here. Speak terms.singular, not the tool name.',
22
- list_leads: 'List open leads for an org. Maps to GET /api/agent/v0/leads. Filter booking=never for leads that never booked a consult (whole company, exact total); booking=cancelled = booked once, every booking cancelled.',
23
+ list_leads: 'List open leads for an org. Maps to GET /api/agent/v0/leads. Filter booking=never for leads that never booked a consult (whole company, exact total); booking=cancelled = booked once, every booking cancelled. booking=held = a consult happened (its outcome says so); held wins over scheduled.',
23
24
  get_lead: 'Get one lead by UUID, including closed ones. Maps to GET /api/agent/v0/leads/:id.',
24
25
  lead_report: 'New / stalled / no next step / unbooked briefing. New is the period (default week-to-date); stalled is the whole company; the other two are among new only. Maps to GET /api/agent/v0/reports/leads.',
25
26
  add_comment: 'Add a plain-text comment on a lead, authored as the owner. Only if the owner asked for it. Maps to POST /api/agent/v0/leads/:id/comments.',
27
+ get_numbers: 'The My numbers sheet for a gym: leads, consults booked and happened, invites, won, close rate, speed to lead, lost and still open, each with the same days of the previous period and the get_list args that open its people. period=week or month (to date, org time zone), or custom with from/to (up to 366 days). source narrows to one lead source. Maps to GET /api/agent/v0/numbers.',
28
+ get_list: 'The people behind a number, as the Reports page and its CSV show them: one row per person, CSV columns (times in the org time zone, waits in minutes). Pass the args get_numbers returned, or a list with a date range on its date columns (came_in=this_month, won=2026-10-01..2026-10-22) and filters. Each key takes a list: any value matches within a key, and keys combine with AND. choices gives each filter\'s values. Up to 100 rows a page. Maps to GET /api/agent/v0/lists.',
26
29
  };
27
30
  export function renderToolDescription(name) {
28
31
  return DESCRIPTIONS[name];
@@ -52,8 +55,9 @@ export function renderSkillMarkdown() {
52
55
  '- Never guess `org_id`. If the user names a company, call `list_orgs` and match `name`; if zero or multiple matches, ask.',
53
56
  '- Who never booked = `list_leads` with `booking=never`, then `booking=cancelled` as a second line. Never answer this from `lead_report.unbooked`. Unbooked is not "everyone who never booked."',
54
57
  '- No next step and Unbooked are **among new** this period, not every open record. Stalled is the whole company.',
58
+ '- Numbers = `get_numbers`; the people behind a number = `get_list` with the args it returned. Never count those from `list_leads`.',
55
59
  '',
56
- '## Tools (five verbs only)',
60
+ '## Tools (seven verbs only)',
57
61
  '',
58
62
  '| Tool | Purpose |',
59
63
  '| --- | --- |',
@@ -62,6 +66,8 @@ export function renderSkillMarkdown() {
62
66
  '| `get_lead` | Fetch one lead by UUID. |',
63
67
  '| `lead_report` | Period report: new / stalled / no_next_step / unbooked (the last two among new). |',
64
68
  '| `add_comment` | Post a plain-text comment on a lead (only if asked). |',
69
+ '| `get_numbers` | The My numbers sheet: counts for a period and source, each with `get_list` args. |',
70
+ '| `get_list` | The people behind a number (Reports page / CSV rows), paged. |',
65
71
  '',
66
72
  '## Auth / config',
67
73
  '',
@@ -81,7 +87,7 @@ export function renderConnectPrompt(input) {
81
87
  `API: ${base}`,
82
88
  'On every request send header: Authorization: Bearer <the key>',
83
89
  '',
84
- 'If you already have Workhive tools named list_orgs, list_leads, get_lead, lead_report, or add_comment, use those.',
90
+ 'If you already have Workhive tools named list_orgs, list_leads, get_lead, lead_report, add_comment, get_numbers, or get_list, use those.',
85
91
  `If you can add a remote MCP connector by URL, add ${base}/mcp and sign in when asked; then use those tools.`,
86
92
  'Otherwise call these HTTP endpoints and parse JSON:',
87
93
  '',
@@ -96,6 +102,10 @@ export function renderConnectPrompt(input) {
96
102
  ' One lead. LEAD_ID is a UUID.',
97
103
  `5. POST ${base}/leads/LEAD_ID/comments?org_id=ORG_ID`,
98
104
  ' Body: {"body":"plain text"}. Only if I ask you to comment. Never invent a call, SMS, or visit.',
105
+ `6. GET ${base}/numbers?org_id=ORG_ID&period=week`,
106
+ ' Gym numbers (owners/admins). period=week, month, or custom with from and to.',
107
+ `7. GET ${base}/lists?org_id=ORG_ID&list=leads&from=YYYY-MM-DD&to=YYYY-MM-DD`,
108
+ ' The people behind a number. Use the list args /numbers returns.',
99
109
  '',
100
110
  'Rules:',
101
111
  '- You are a client of Workhive, not the in-app SDR.',
@@ -128,6 +138,7 @@ export function renderUniversalPrompt(input) {
128
138
  '- Claude: Customize, Add connector, Add custom connector, paste the address above, press Allow when Workhive asks.',
129
139
  '- ChatGPT: turn on Developer mode under Security and login, then Plugins, the plus button, Create app, paste the address above.',
130
140
  '- Grok: Connectors, New Connector, Custom, paste the address above.',
141
+ '- Grok Bot: you can do this yourself: add the MCP server at the address above, then show me the connect card so I can press Sign in.',
131
142
  '',
132
143
  'Either way, finish by calling list_orgs. Read terms and rules_version. Then say only: "Ready. Workhive is connected as <company name>."',
133
144
  ].join('\n');
package/dist/tools.js CHANGED
@@ -44,12 +44,19 @@ function requireLeadId(args) {
44
44
  throw new Error('id is required');
45
45
  return id;
46
46
  }
47
+ /** A filter's values travel as an array of strings; anything else as one string. */
47
48
  function pickQuery(args, keys) {
48
49
  const query = {};
49
50
  for (const key of keys) {
50
51
  const value = args[key];
51
52
  if (value == null || value === '')
52
53
  continue;
54
+ if (Array.isArray(value)) {
55
+ const values = value.filter((item) => typeof item === 'string' && item !== '');
56
+ if (values.length > 0)
57
+ query[key] = values;
58
+ continue;
59
+ }
53
60
  query[key] = typeof value === 'boolean' ? (value ? 'true' : 'false') : String(value);
54
61
  }
55
62
  return query;
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@workhive/agent",
3
- "version": "0.2.0",
4
- "description": "Workhive Agent Kernel MCP adapter. Five tools 1:1 with REST /api/agent/v0 over stdio.",
3
+ "version": "0.3.0",
4
+ "description": "Workhive Agent Kernel MCP adapter. Seven tools 1:1 with REST /api/agent/v0 over stdio.",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "workhive-agent": "./dist/index.js"
@@ -26,7 +26,7 @@
26
26
  "node": ">=18"
27
27
  },
28
28
  "dependencies": {
29
- "@modelcontextprotocol/sdk": "1.30.0"
29
+ "@modelcontextprotocol/sdk": "1.32.1"
30
30
  },
31
31
  "devDependencies": {
32
32
  "typescript": "^5.0.0"