talentprism-cli 0.3.1__tar.gz → 0.4.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.
Files changed (30) hide show
  1. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/PKG-INFO +4 -4
  2. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/pyproject.toml +1 -1
  3. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli/README.md +3 -3
  4. talentprism_cli-0.4.0/talentprism_cli/__init__.py +1 -0
  5. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli/cli.py +66 -45
  6. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli/readonly_api.py +61 -7
  7. talentprism_cli-0.4.0/talentprism_cli/record_reads.py +175 -0
  8. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli/skill.py +29 -11
  9. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli/transport.py +5 -26
  10. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli.egg-info/PKG-INFO +4 -4
  11. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli.egg-info/SOURCES.txt +1 -0
  12. talentprism_cli-0.3.1/talentprism_cli/__init__.py +0 -1
  13. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/README.md +0 -0
  14. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/setup.cfg +0 -0
  15. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli/LICENSE.txt +0 -0
  16. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli/__main__.py +0 -0
  17. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli/auth.py +0 -0
  18. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli/config.py +0 -0
  19. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli/config_store.py +0 -0
  20. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli/credentials.py +0 -0
  21. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli/errors.py +0 -0
  22. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli/format.py +0 -0
  23. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli/loopback.py +0 -0
  24. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli/network_bootstrap.py +0 -0
  25. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli/oauth.py +0 -0
  26. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli/sequence_writes.py +0 -0
  27. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli.egg-info/dependency_links.txt +0 -0
  28. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli.egg-info/entry_points.txt +0 -0
  29. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli.egg-info/requires.txt +0 -0
  30. {talentprism_cli-0.3.1 → talentprism_cli-0.4.0}/talentprism_cli.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: talentprism-cli
3
- Version: 0.3.1
3
+ Version: 0.4.0
4
4
  Summary: Command line for TalentPrism: team-scoped recruiting data and actions for people and AI agents
5
5
  License-Expression: LicenseRef-Proprietary
6
6
  Project-URL: Homepage, https://talentprism.ai
@@ -65,13 +65,13 @@ When several credentials are present, `tp` uses the first of: the `--api-key` fl
65
65
  tp whoami
66
66
  tp sequences list --status Active --json
67
67
  tp candidates search --query "aircraft assembler North Charleston" --json
68
- tp candidates search --query "welder" --limit 20 --json
69
68
  tp activity summary --days 14 --json
70
69
  tp candidates timeline <candidate_id> --days 30 --json
70
+ tp chats messages --candidates 101,102 --role human --since 2026-11-01 --json
71
+ tp applications list --job 217565 --json
72
+ tp agent-runs list --chat-id 4204 --entries --json
71
73
  ```
72
74
 
73
- List commands stop with `too_many_results` when a list has more than 100 items. Add `--limit N` for the first N rows in the server's order (the result keeps `count`, the server's total, and sets `truncated`), or `--all` to fetch every page. The two cannot be combined.
74
-
75
75
  ## Changing data
76
76
 
77
77
  Every write is two steps. Run the command once to get a preview and a one-time approval token. Nothing changes. Then run the same command again with `--confirm-write --approval-token <token>`:
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "talentprism-cli"
7
- version = "0.3.1"
7
+ version = "0.4.0"
8
8
  description = "Command line for TalentPrism: team-scoped recruiting data and actions for people and AI agents"
9
9
  readme = "talentprism_cli/README.md"
10
10
  license = "LicenseRef-Proprietary"
@@ -42,13 +42,13 @@ When several credentials are present, `tp` uses the first of: the `--api-key` fl
42
42
  tp whoami
43
43
  tp sequences list --status Active --json
44
44
  tp candidates search --query "aircraft assembler North Charleston" --json
45
- tp candidates search --query "welder" --limit 20 --json
46
45
  tp activity summary --days 14 --json
47
46
  tp candidates timeline <candidate_id> --days 30 --json
47
+ tp chats messages --candidates 101,102 --role human --since 2026-11-01 --json
48
+ tp applications list --job 217565 --json
49
+ tp agent-runs list --chat-id 4204 --entries --json
48
50
  ```
49
51
 
50
- List commands stop with `too_many_results` when a list has more than 100 items. Add `--limit N` for the first N rows in the server's order (the result keeps `count`, the server's total, and sets `truncated`), or `--all` to fetch every page. The two cannot be combined.
51
-
52
52
  ## Changing data
53
53
 
54
54
  Every write is two steps. Run the command once to get a preview and a one-time approval token. Nothing changes. Then run the same command again with `--confirm-write --approval-token <token>`:
@@ -0,0 +1 @@
1
+ __version__ = "0.4.0"
@@ -12,6 +12,15 @@ from .auth import login, logout
12
12
  from .config import config_status, resolve_config, set_active_profile, set_profile_values
13
13
  from .errors import TalentPrismError, missing_api_key_error
14
14
  from .format import format_output
15
+ from .record_reads import (
16
+ RECORD_LIST_COMMANDS,
17
+ add_delivery_filters,
18
+ add_message_filters,
19
+ add_record_list_commands,
20
+ delivery_inputs,
21
+ message_inputs,
22
+ record_list_request,
23
+ )
15
24
  from .sequence_writes import SEQUENCE_WRITE_ACTIONS, load_sequence_file, sequence_write_request
16
25
  from .skill import COMMANDS, skill_markdown
17
26
  from .transport import APIClient, RequestFn
@@ -133,7 +142,6 @@ def _build_parser() -> argparse.ArgumentParser:
133
142
  sequences_list = sequence_subparsers.add_parser("list", parents=[common])
134
143
  sequences_list.add_argument("--status")
135
144
  sequences_list.add_argument("--all", action="store_true")
136
- sequences_list.add_argument("--limit", type=int)
137
145
  sequences_show = sequence_subparsers.add_parser("show", parents=[common])
138
146
  sequences_show.add_argument("sequence_id")
139
147
  sequences_summary = sequence_subparsers.add_parser("summary", parents=[common])
@@ -158,15 +166,14 @@ def _build_parser() -> argparse.ArgumentParser:
158
166
  candidates_list = candidate_subparsers.add_parser("list", parents=[common])
159
167
  candidates_list.add_argument("--sequence", required=True)
160
168
  candidates_list.add_argument("--all", action="store_true")
161
- candidates_list.add_argument("--limit", type=int)
162
169
  candidates_search = candidate_subparsers.add_parser("search", parents=[common])
163
170
  candidates_search.add_argument("--query", required=True)
164
171
  candidates_search.add_argument("--all", action="store_true")
165
- candidates_search.add_argument("--limit", type=int)
166
172
  candidates_show = candidate_subparsers.add_parser("show", parents=[common])
167
173
  candidates_show.add_argument("candidate_id")
168
174
  candidates_show.add_argument("--conversations", action="store_true")
169
175
  candidates_show.add_argument("--reminders", action="store_true")
176
+ candidates_show.add_argument("--memory", action="store_true", help="Include the current CandidateMemory facts.")
170
177
  candidates_add_note = candidate_subparsers.add_parser("add-note", parents=[common])
171
178
  candidates_add_note.add_argument("candidate_id", type=int)
172
179
  candidates_add_note.add_argument("--text", required=True)
@@ -188,7 +195,6 @@ def _build_parser() -> argparse.ArgumentParser:
188
195
  candidates_engaged = candidate_subparsers.add_parser("engaged", parents=[common])
189
196
  candidates_engaged.add_argument("--sequence", required=True)
190
197
  candidates_engaged.add_argument("--all", action="store_true")
191
- candidates_engaged.add_argument("--limit", type=int)
192
198
  # Slice 2 evidence reads: the record behind a claim, not just the claim.
193
199
  candidates_provenance = candidate_subparsers.add_parser("provenance", parents=[common])
194
200
  candidates_provenance.add_argument("candidate_id", type=int)
@@ -224,7 +230,6 @@ def _build_parser() -> argparse.ArgumentParser:
224
230
  reminders_list.add_argument("--due")
225
231
  reminders_list.add_argument("--status")
226
232
  reminders_list.add_argument("--all", action="store_true")
227
- reminders_list.add_argument("--limit", type=int)
228
233
  reminders_create = reminders_subparsers.add_parser("create", parents=[common])
229
234
  reminders_create.add_argument("--candidate", type=int)
230
235
  reminders_create.add_argument("--due", required=True)
@@ -281,7 +286,6 @@ def _build_parser() -> argparse.ArgumentParser:
281
286
  interviews_list = interview_subparsers.add_parser("list", parents=[common])
282
287
  interviews_list.add_argument("--sequence", required=True)
283
288
  interviews_list.add_argument("--all", action="store_true")
284
- interviews_list.add_argument("--limit", type=int)
285
289
  interviews_show = interview_subparsers.add_parser("show", parents=[common])
286
290
  interviews_show.add_argument("interview_id")
287
291
  interviews_create_link = interview_subparsers.add_parser("create-link", parents=[common])
@@ -325,12 +329,23 @@ def _build_parser() -> argparse.ArgumentParser:
325
329
  chats_summary.add_argument("--limit", type=int)
326
330
  chats_messages = chats_subparsers.add_parser("messages", parents=[common])
327
331
  chats_messages.add_argument("--chat-id", type=int)
328
- chats_messages.add_argument("--days", type=int, default=7)
332
+ # No default: a chat-scoped read covers the whole transcript; the server defaults others to 7 days.
333
+ chats_messages.add_argument("--days", type=int)
329
334
  chats_messages.add_argument("--sequence")
330
335
  chats_messages.add_argument("--candidate", type=int)
331
336
  chats_messages.add_argument("--limit", type=int)
337
+ add_message_filters(chats_messages)
332
338
  chats_diagnose = chats_subparsers.add_parser("diagnose", parents=[common])
333
339
  chats_diagnose.add_argument("--chat-id", type=int, required=True)
340
+ chats_reply_invariant = chats_subparsers.add_parser("reply-invariant", parents=[common])
341
+ chats_reply_invariant.add_argument("--days", type=int, default=1)
342
+ chats_findings = chats_subparsers.add_parser("findings", parents=[common])
343
+ chats_findings.add_argument("--since", type=int, default=1, help="Days of stored nightly findings (default 1).")
344
+ chats_findings.add_argument("--check")
345
+ chats_findings.add_argument("--chat-id", type=int)
346
+ chats_findings.add_argument("--severity")
347
+ chats_findings.add_argument("--include-resolved", action="store_true")
348
+ chats_findings.add_argument("--limit", type=int)
334
349
 
335
350
  # `tp ops ...` replaces the hand-built `kamal app exec ... manage.py shell` one-liners that
336
351
  # every prod diagnostic used to be (issue #474). Deploys stay on kamal; diagnostics do not.
@@ -342,6 +357,7 @@ def _build_parser() -> argparse.ArgumentParser:
342
357
  ops_delivery.add_argument("--channel", choices=["sms", "email", "phone"])
343
358
  ops_delivery.add_argument("--days", type=int, default=3)
344
359
  ops_delivery.add_argument("--limit", type=int)
360
+ add_delivery_filters(ops_delivery)
345
361
  ops_decisions = ops_subparsers.add_parser("decision-logs", parents=[common])
346
362
  ops_decisions.add_argument("--loop", choices=["nudge", "keepwarm"])
347
363
  ops_decisions.add_argument("--days", type=int, default=3)
@@ -351,6 +367,9 @@ def _build_parser() -> argparse.ArgumentParser:
351
367
  ops_decisions.add_argument("--skip-reason")
352
368
  ops_decisions.add_argument("--limit", type=int)
353
369
 
370
+ # Issue #778: cross-record reads that replace hand-written production shell queries.
371
+ add_record_list_commands(subparsers, [common], parser_class=TalentPrismArgumentParser)
372
+
354
373
  actions_parser = subparsers.add_parser("recruiter-actions")
355
374
  actions_subparsers = actions_parser.add_subparsers(
356
375
  dest="action", required=True, parser_class=TalentPrismArgumentParser
@@ -413,26 +432,6 @@ class TalentPrismArgumentParser(argparse.ArgumentParser):
413
432
  )
414
433
 
415
434
 
416
- def _page_options(args: argparse.Namespace) -> dict:
417
- """Turn --all / --limit into get_paginated keywords, refusing combinations that make no sense."""
418
- if args.limit is not None and args.all:
419
- raise TalentPrismError(
420
- code="invalid_input",
421
- type="invalid_input",
422
- message="--limit and --all cannot be used together.",
423
- remediation="Use --limit N for the first N rows, or --all for every row.",
424
- )
425
- if args.limit is not None and args.limit < 1:
426
- raise TalentPrismError(
427
- code="invalid_input",
428
- type="invalid_input",
429
- message="--limit must be a positive integer.",
430
- details={"limit": args.limit},
431
- remediation="Pass --limit with a number of 1 or more.",
432
- )
433
- return {"all_pages": args.all, "limit": args.limit}
434
-
435
-
436
435
  def _add_write_approval_arguments(parser: argparse.ArgumentParser) -> None:
437
436
  parser.add_argument("--confirm-write", action="store_true")
438
437
  parser.add_argument("--approval-token")
@@ -504,6 +503,9 @@ def _dispatch(args: argparse.Namespace, client: APIClient, stderr: TextIO):
504
503
  return _dispatch_ops(args, client)
505
504
  if args.command == "recruiter-actions":
506
505
  return _dispatch_recruiter_actions(args, client)
506
+ if args.command in RECORD_LIST_COMMANDS:
507
+ capability, inputs = record_list_request(args)
508
+ return _read_capability(client, capability, inputs)
507
509
  if args.command == "team-config":
508
510
  return _dispatch_team_config(args, client)
509
511
  raise TalentPrismError(
@@ -561,7 +563,7 @@ def _dispatch_sequences(args: argparse.Namespace, client: APIClient):
561
563
  if args.action == "list":
562
564
  query = urlencode({"status": args.status}) if args.status else ""
563
565
  suffix = f"?{query}" if query else ""
564
- return client.get_paginated(f"/api/sequences/{suffix}", **_page_options(args))
566
+ return client.get_paginated(f"/api/sequences/{suffix}", all_pages=args.all)
565
567
  if args.action == "show":
566
568
  return client.get(f"/api/sequences/{args.sequence_id}/")
567
569
  if args.action == "summary":
@@ -581,16 +583,18 @@ def _dispatch_sequences(args: argparse.Namespace, client: APIClient):
581
583
 
582
584
  def _dispatch_candidates(args: argparse.Namespace, client: APIClient):
583
585
  if args.action == "list":
584
- return client.get_paginated(f"/api/sequences/{args.sequence}/candidates/", **_page_options(args))
586
+ return client.get_paginated(f"/api/sequences/{args.sequence}/candidates/", all_pages=args.all)
585
587
  if args.action == "search":
586
588
  query = urlencode({"query": args.query})
587
- return client.get_paginated(f"/api/candidates/search/?{query}", **_page_options(args))
589
+ return client.get_paginated(f"/api/candidates/search/?{query}", all_pages=args.all)
588
590
  if args.action == "show":
589
591
  params = {}
590
592
  if args.conversations:
591
593
  params["conversations"] = "1"
592
594
  if args.reminders:
593
595
  params["reminders"] = "1"
596
+ if args.memory:
597
+ params["memory"] = "1"
594
598
  query = urlencode(params)
595
599
  suffix = f"?{query}" if query else ""
596
600
  return client.get(f"/api/candidates/{args.candidate_id}/{suffix}")
@@ -636,7 +640,7 @@ def _dispatch_candidates(args: argparse.Namespace, client: APIClient):
636
640
  command="tp candidates send-sms",
637
641
  )
638
642
  if args.action == "engaged":
639
- return client.get_paginated(f"/api/sequences/{args.sequence}/candidates/engaged/", **_page_options(args))
643
+ return client.get_paginated(f"/api/sequences/{args.sequence}/candidates/engaged/", all_pages=args.all)
640
644
  if args.action == "provenance":
641
645
  return _read_capability(
642
646
  client,
@@ -700,7 +704,7 @@ def _dispatch_reminders(args: argparse.Namespace, client: APIClient):
700
704
  params["status"] = args.status
701
705
  query = urlencode(params)
702
706
  suffix = f"?{query}" if query else ""
703
- return client.get_paginated(f"/api/reminders/{suffix}", **_page_options(args))
707
+ return client.get_paginated(f"/api/reminders/{suffix}", all_pages=args.all)
704
708
  if args.action == "create":
705
709
  payload = {"candidate_id": args.candidate, "due": args.due, "text": args.text}
706
710
  if args.candidate is None:
@@ -818,12 +822,26 @@ def _dispatch_chats(args: argparse.Namespace, client: APIClient):
818
822
  if args.action == "messages":
819
823
  if args.chat_id is not None:
820
824
  inputs["chat_id"] = args.chat_id
821
- return client.post(
822
- "/api/capabilities/invoke/",
823
- {"capability": "chats.messages", "inputs": inputs, "confirmed_write": False},
824
- )
825
+ inputs.update(message_inputs(args))
826
+ return _read_capability(client, "chats.messages", inputs)
825
827
  if args.action == "diagnose":
826
828
  return _read_capability(client, "chats.diagnose", {"chat_id": args.chat_id})
829
+ if args.action == "reply-invariant":
830
+ return _read_capability(client, "chats.reply_invariant", {"days": args.days})
831
+ if args.action == "findings":
832
+ return _read_capability(
833
+ client,
834
+ "chats.findings",
835
+ _optional_inputs(
836
+ args,
837
+ since="days",
838
+ check="check",
839
+ chat_id="chat_id",
840
+ severity="severity",
841
+ include_resolved="include_resolved",
842
+ limit="limit",
843
+ ),
844
+ )
827
845
  raise TalentPrismError(
828
846
  code="invalid_command",
829
847
  type="invalid_input",
@@ -837,14 +855,17 @@ def _dispatch_ops(args: argparse.Namespace, client: APIClient):
837
855
  return _read_capability(
838
856
  client,
839
857
  "ops.delivery_status",
840
- _optional_inputs(
841
- args,
842
- candidate="candidate_id",
843
- sequence="sequence_id",
844
- channel="channel",
845
- days="days",
846
- limit="limit",
847
- ),
858
+ {
859
+ **_optional_inputs(
860
+ args,
861
+ candidate="candidate_id",
862
+ sequence="sequence_id",
863
+ channel="channel",
864
+ days="days",
865
+ limit="limit",
866
+ ),
867
+ **delivery_inputs(args),
868
+ },
848
869
  )
849
870
  if args.action == "decision-logs":
850
871
  return _read_capability(
@@ -1037,7 +1058,7 @@ def _dispatch_copilot(args: argparse.Namespace, client: APIClient):
1037
1058
 
1038
1059
  def _dispatch_interviews(args: argparse.Namespace, client: APIClient):
1039
1060
  if args.action == "list":
1040
- return client.get_paginated(f"/api/sequences/{args.sequence}/interviews/", **_page_options(args))
1061
+ return client.get_paginated(f"/api/sequences/{args.sequence}/interviews/", all_pages=args.all)
1041
1062
  if args.action == "show":
1042
1063
  return client.get(f"/api/interviews/{args.interview_id}/")
1043
1064
  if args.action == "create-link":
@@ -10,6 +10,15 @@ from .config import resolve_config
10
10
  from .errors import TalentPrismError
11
11
  from .format import format_output
12
12
  from .network_bootstrap import bootstrap_network_from_env
13
+ from .record_reads import (
14
+ RECORD_LIST_COMMANDS,
15
+ add_delivery_filters,
16
+ add_message_filters,
17
+ add_record_list_commands,
18
+ delivery_inputs,
19
+ message_inputs,
20
+ record_list_request,
21
+ )
13
22
  from .transport import APIClient, RequestFn
14
23
 
15
24
 
@@ -82,13 +91,29 @@ def _build_parser() -> argparse.ArgumentParser:
82
91
  chats_summary.add_argument("--limit", type=int)
83
92
  chats_summary.add_argument("--json", action="store_true")
84
93
  chats_messages = chats_subparsers.add_parser("messages")
85
- chats_messages.add_argument("--chat-id", type=int, required=True)
86
- chats_messages.add_argument("--days", type=int, default=7)
94
+ chats_messages.add_argument("--chat-id", type=int)
95
+ # No default: a chat-scoped read covers the whole transcript; the server defaults others to 7 days.
96
+ chats_messages.add_argument("--days", type=int)
97
+ chats_messages.add_argument("--sequence")
98
+ chats_messages.add_argument("--candidate", type=int)
87
99
  chats_messages.add_argument("--limit", type=int)
100
+ add_message_filters(chats_messages)
88
101
  chats_messages.add_argument("--json", action="store_true")
89
102
  chats_diagnose = chats_subparsers.add_parser("diagnose")
90
103
  chats_diagnose.add_argument("--chat-id", type=int, required=True)
91
104
  chats_diagnose.add_argument("--json", action="store_true")
105
+ chats_reply_invariant = chats_subparsers.add_parser("reply-invariant")
106
+ chats_reply_invariant.add_argument("--days", type=int, default=1)
107
+ chats_reply_invariant.add_argument("--json", action="store_true")
108
+ # Stored nightly findings for the team (chats.findings); --since is in days.
109
+ chats_findings = chats_subparsers.add_parser("findings")
110
+ chats_findings.add_argument("--since", type=int, default=1)
111
+ chats_findings.add_argument("--check")
112
+ chats_findings.add_argument("--chat-id", type=int)
113
+ chats_findings.add_argument("--severity")
114
+ chats_findings.add_argument("--include-resolved", action="store_true")
115
+ chats_findings.add_argument("--limit", type=int)
116
+ chats_findings.add_argument("--json", action="store_true")
92
117
 
93
118
  # Read-only prod diagnostics. These exist here, not only in cli.py, because the health sweep
94
119
  # runs through this path and must never be able to reach a write.
@@ -100,6 +125,7 @@ def _build_parser() -> argparse.ArgumentParser:
100
125
  ops_delivery.add_argument("--channel", choices=["sms", "email", "phone"])
101
126
  ops_delivery.add_argument("--days", type=int, default=3)
102
127
  ops_delivery.add_argument("--limit", type=int)
128
+ add_delivery_filters(ops_delivery)
103
129
  ops_delivery.add_argument("--json", action="store_true")
104
130
  ops_decisions = ops_subparsers.add_parser("decision-logs")
105
131
  ops_decisions.add_argument("--loop", choices=["nudge", "keepwarm"])
@@ -144,6 +170,7 @@ def _build_parser() -> argparse.ArgumentParser:
144
170
  candidates_show.add_argument("candidate_id")
145
171
  candidates_show.add_argument("--conversations", action="store_true")
146
172
  candidates_show.add_argument("--reminders", action="store_true")
173
+ candidates_show.add_argument("--memory", action="store_true")
147
174
  candidates_show.add_argument("--json", action="store_true")
148
175
  # Slice 2 evidence reads. They belong on the read-only path too: the health sweep asks
149
176
  # "did this actually persist?" and must never be able to reach a write to find out.
@@ -176,6 +203,11 @@ def _build_parser() -> argparse.ArgumentParser:
176
203
  leads_consent.add_argument("--limit", type=int)
177
204
  leads_consent.add_argument("--json", action="store_true")
178
205
 
206
+ # Issue #778 list reads: applications, agent-runs, job-alerts. All read capabilities.
207
+ json_flag = argparse.ArgumentParser(add_help=False)
208
+ json_flag.add_argument("--json", action="store_true")
209
+ add_record_list_commands(subparsers, [json_flag])
210
+
179
211
  capabilities = subparsers.add_parser("capabilities")
180
212
  capabilities_subparsers = capabilities.add_subparsers(dest="action", required=True)
181
213
  capabilities_invoke = capabilities_subparsers.add_parser("invoke")
@@ -193,7 +225,13 @@ def _dispatch(args: argparse.Namespace, client: APIClient):
193
225
  if args.action == "diagnose":
194
226
  # Diagnose is scoped to one chat, so it takes no window flags to read here.
195
227
  return _invoke_capability(client, "chats.diagnose", {"chat_id": args.chat_id})
196
- inputs: dict[str, object] = {"days": args.days}
228
+ if args.action == "reply-invariant":
229
+ return _invoke_capability(client, "chats.reply_invariant", {"days": args.days})
230
+ if args.action == "findings":
231
+ return _invoke_capability(client, "chats.findings", _set_inputs(args, _FINDINGS_INPUTS))
232
+ inputs: dict[str, object] = {}
233
+ if getattr(args, "days", None) is not None:
234
+ inputs["days"] = args.days
197
235
  if getattr(args, "limit", None):
198
236
  inputs["limit"] = args.limit
199
237
  if getattr(args, "sequence", None):
@@ -203,11 +241,14 @@ def _dispatch(args: argparse.Namespace, client: APIClient):
203
241
  if args.action == "summary":
204
242
  return _invoke_capability(client, "chats.summary", inputs)
205
243
  if args.action == "messages":
206
- inputs["chat_id"] = args.chat_id
244
+ if args.chat_id is not None:
245
+ inputs["chat_id"] = args.chat_id
246
+ inputs.update(message_inputs(args))
207
247
  return _invoke_capability(client, "chats.messages", inputs)
208
248
  if args.command == "ops":
209
249
  if args.action == "delivery-status":
210
- return _invoke_capability(client, "ops.delivery_status", _set_inputs(args, _DELIVERY_INPUTS))
250
+ inputs = {**_set_inputs(args, _DELIVERY_INPUTS), **delivery_inputs(args)}
251
+ return _invoke_capability(client, "ops.delivery_status", inputs)
211
252
  if args.action == "decision-logs":
212
253
  return _invoke_capability(client, "ops.decision_logs", _set_inputs(args, _DECISION_INPUTS))
213
254
  if args.command == "recruiter-actions":
@@ -229,6 +270,8 @@ def _dispatch(args: argparse.Namespace, client: APIClient):
229
270
  params["conversations"] = "1"
230
271
  if args.reminders:
231
272
  params["reminders"] = "1"
273
+ if args.memory:
274
+ params["memory"] = "1"
232
275
  query = urlencode(params)
233
276
  suffix = f"?{query}" if query else ""
234
277
  return client.get(f"/api/candidates/{args.candidate_id}/{suffix}")
@@ -241,6 +284,9 @@ def _dispatch(args: argparse.Namespace, client: APIClient):
241
284
  return _invoke_capability(client, "leads.maturity", {"candidate_id": args.candidate_id})
242
285
  if args.action == "consent-evidence":
243
286
  return _invoke_capability(client, "leads.consent_evidence", _set_inputs(args, _CONSENT_SWEEP_INPUTS))
287
+ if args.command in RECORD_LIST_COMMANDS:
288
+ capability, inputs = record_list_request(args)
289
+ return _invoke_capability(client, capability, inputs)
244
290
  if args.command == "capabilities" and args.action == "invoke":
245
291
  return _invoke_capability(client, args.capability, _load_json_object(args.input_json))
246
292
  raise TalentPrismError(
@@ -248,14 +294,22 @@ def _dispatch(args: argparse.Namespace, client: APIClient):
248
294
  type="invalid_input",
249
295
  message="Unsupported read-only command.",
250
296
  remediation=(
251
- "Use whoami, chats summary/messages/diagnose, ops delivery-status/decision-logs, "
297
+ "Use whoami, chats summary/messages/diagnose/reply-invariant, ops delivery-status/decision-logs, "
252
298
  "recruiter-actions list/show, team-config read/senders/compare, "
253
299
  "candidates show/provenance/timeline/records, leads maturity/consent-evidence, "
254
- "or capabilities invoke."
300
+ "applications list, agent-runs list, job-alerts list, or capabilities invoke."
255
301
  ),
256
302
  )
257
303
 
258
304
 
305
+ _FINDINGS_INPUTS = {
306
+ "since": "days",
307
+ "check": "check",
308
+ "chat_id": "chat_id",
309
+ "severity": "severity",
310
+ "include_resolved": "include_resolved",
311
+ "limit": "limit",
312
+ }
259
313
  _DELIVERY_INPUTS = {
260
314
  "candidate": "candidate_id",
261
315
  "sequence": "sequence_id",
@@ -0,0 +1,175 @@
1
+ """Cross-record read commands (issue #778), shared by `tp` and the read-only `tp-readonly` path.
2
+
3
+ Both entry points build the same flags and send the same capability inputs, so they live here
4
+ once: the new `tp chats messages` and `tp ops delivery-status` filters, and the three list
5
+ commands `tp applications list`, `tp agent-runs list` and `tp job-alerts list`. Every one is a
6
+ read capability; nothing here can reach a write.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import argparse
12
+
13
+ from .errors import TalentPrismError
14
+
15
+ RECORD_LIST_COMMANDS = ("applications", "agent-runs", "job-alerts")
16
+
17
+ _PAGING = {"days": "days", "since": "since", "until": "until", "limit": "limit", "offset": "offset"}
18
+
19
+
20
+ def add_range_arguments(parser: argparse.ArgumentParser) -> None:
21
+ parser.add_argument("--since", help="ISO date or datetime, inclusive. Wins over --days.")
22
+ parser.add_argument("--until", help="ISO date (through the end of that day) or datetime.")
23
+
24
+
25
+ def add_message_filters(parser: argparse.ArgumentParser) -> None:
26
+ """`chats messages` flags beyond --chat-id/--days/--sequence/--candidate/--limit."""
27
+ parser.add_argument("--chat-ids", help="Comma-separated chat ids.")
28
+ parser.add_argument("--candidates", help="Comma-separated candidate ids.")
29
+ parser.add_argument("--campaign", help="Campaign (round) UUID.")
30
+ parser.add_argument("--search", help="Case-insensitive text the message contains.")
31
+ parser.add_argument(
32
+ "--role", help="human, ai (default); system, worker, wait or all need an admin key. Comma separated."
33
+ )
34
+ add_range_arguments(parser)
35
+ parser.add_argument("--offset", type=int, help="Skip this many newer matches (the previous next_offset).")
36
+
37
+
38
+ def message_inputs(args: argparse.Namespace) -> dict:
39
+ return {
40
+ **set_inputs(
41
+ args,
42
+ {
43
+ "campaign": "campaign_id",
44
+ "search": "search",
45
+ "role": "role",
46
+ "since": "since",
47
+ "until": "until",
48
+ "offset": "offset",
49
+ },
50
+ ),
51
+ **id_list_inputs(args, {"chat_ids": "chat_ids", "candidates": "candidate_ids"}),
52
+ }
53
+
54
+
55
+ def add_delivery_filters(parser: argparse.ArgumentParser) -> None:
56
+ """`ops delivery-status` flags beyond --candidate/--sequence/--channel/--days/--limit."""
57
+ parser.add_argument("--candidates", help="Comma-separated candidate ids.")
58
+ parser.add_argument("--campaign", help="Campaign (round) UUID.")
59
+ parser.add_argument("--source", help="Exact send source tag, e.g. keepwarm or a batch name.")
60
+ add_range_arguments(parser)
61
+
62
+
63
+ def delivery_inputs(args: argparse.Namespace) -> dict:
64
+ return {
65
+ **set_inputs(args, {"campaign": "campaign_id", "source": "source", "since": "since", "until": "until"}),
66
+ **id_list_inputs(args, {"candidates": "candidate_ids"}),
67
+ }
68
+
69
+
70
+ def add_record_list_commands(subparsers, parents: list[argparse.ArgumentParser], parser_class=None) -> None:
71
+ def list_parser(command: str, help_text: str) -> argparse.ArgumentParser:
72
+ group = subparsers.add_parser(command, help=help_text)
73
+ kwargs = {"dest": "action", "required": True}
74
+ if parser_class is not None:
75
+ kwargs["parser_class"] = parser_class
76
+ parser = group.add_subparsers(**kwargs).add_parser("list", parents=parents)
77
+ parser.add_argument("--candidate", type=int)
78
+ parser.add_argument("--candidates", help="Comma-separated candidate ids.")
79
+ return parser
80
+
81
+ applications = list_parser("applications", "Job applications across the team.")
82
+ applications.add_argument("--job", help="Client job id, or several comma separated.")
83
+ applications.add_argument("--campaign", help="Campaign (round) UUID the application is credited to.")
84
+ applications.add_argument("--sequence")
85
+ applications.add_argument("--channel", help="source_channel, e.g. campaign or chat_widget.")
86
+ applications.add_argument("--status")
87
+ _add_paging(applications)
88
+
89
+ runs = list_parser("agent-runs", "TinyLLM worker runs (ExecutionRun).")
90
+ runs.add_argument("--chat-id", type=int)
91
+ runs.add_argument("--chat-ids", help="Comma-separated chat ids.")
92
+ runs.add_argument("--agent", help="Worker name, matched on any part.")
93
+ runs.add_argument("--status", choices=["pending", "running", "succeeded", "failed"])
94
+ runs.add_argument("--errors-only", action="store_true")
95
+ runs.add_argument("--entries", action="store_true", help="Include each run's transcript.")
96
+ runs.add_argument("--include-simulator", action="store_true")
97
+ _add_paging(runs)
98
+
99
+ alerts = list_parser("job-alerts", "Job-alert subscriptions across the team.")
100
+ alerts.add_argument("--active-only", action="store_true")
101
+ alerts.add_argument("--role", help="Job role, matched on any part.")
102
+ alerts.add_argument("--location", help="Location, matched on any part.")
103
+ _add_paging(alerts)
104
+
105
+
106
+ def record_list_request(args: argparse.Namespace) -> tuple[str, dict]:
107
+ """The capability and inputs for `applications|agent-runs|job-alerts list`."""
108
+ if args.command == "applications":
109
+ capability = "applications.list"
110
+ mapping = {
111
+ "job": "job_id",
112
+ "campaign": "campaign_id",
113
+ "sequence": "sequence_id",
114
+ "channel": "source_channel",
115
+ "status": "status",
116
+ }
117
+ elif args.command == "agent-runs":
118
+ capability = "agent_runs.list"
119
+ mapping = {
120
+ "chat_id": "chat_id",
121
+ "agent": "agent_name",
122
+ "status": "status",
123
+ "errors_only": "errors_only",
124
+ "entries": "include_entries",
125
+ "include_simulator": "include_simulator",
126
+ }
127
+ elif args.command == "job-alerts":
128
+ capability = "job_alerts.list"
129
+ mapping = {"active_only": "active_only", "role": "job_role", "location": "location"}
130
+ else:
131
+ raise TalentPrismError(
132
+ code="invalid_command",
133
+ type="invalid_input",
134
+ message="Unknown record list command.",
135
+ remediation="Use tp applications list, tp agent-runs list or tp job-alerts list.",
136
+ )
137
+ inputs = set_inputs(args, {"candidate": "candidate_id", **mapping, **_PAGING})
138
+ inputs.update(id_list_inputs(args, {"candidates": "candidate_ids", "chat_ids": "chat_ids"}))
139
+ return capability, inputs
140
+
141
+
142
+ def set_inputs(args: argparse.Namespace, mapping: dict[str, str]) -> dict:
143
+ """Only the flags the operator actually set; omitted ones fall through to capability defaults."""
144
+ inputs = {}
145
+ for arg_name, input_name in mapping.items():
146
+ value = getattr(args, arg_name, None)
147
+ if value not in (None, "", False):
148
+ inputs[input_name] = value
149
+ return inputs
150
+
151
+
152
+ def id_list_inputs(args: argparse.Namespace, mapping: dict[str, str]) -> dict:
153
+ """Comma-separated id flags become integer lists, refused here if one is not a number."""
154
+ inputs = {}
155
+ for arg_name, input_name in mapping.items():
156
+ raw = getattr(args, arg_name, None)
157
+ if not raw:
158
+ continue
159
+ try:
160
+ inputs[input_name] = [int(part) for part in str(raw).split(",") if part.strip()]
161
+ except ValueError:
162
+ raise TalentPrismError(
163
+ code="invalid_input",
164
+ type="invalid_input",
165
+ message=f"--{arg_name.replace('_', '-')} expects comma-separated ids, got {raw!r}.",
166
+ remediation="Pass ids like --candidates 101,102,103.",
167
+ ) from None
168
+ return inputs
169
+
170
+
171
+ def _add_paging(parser: argparse.ArgumentParser) -> None:
172
+ parser.add_argument("--days", type=int)
173
+ add_range_arguments(parser)
174
+ parser.add_argument("--limit", type=int)
175
+ parser.add_argument("--offset", type=int, help="Skip this many rows (the previous next_offset).")
@@ -8,22 +8,22 @@ COMMANDS = [
8
8
  "tp config set <name> [--api-key <key>] [--base-url <url>]",
9
9
  "tp config set-profile <name>",
10
10
  "tp whoami",
11
- "tp sequences list [--status <status>] [--all] [--limit <n>]",
11
+ "tp sequences list [--status <status>] [--all]",
12
12
  "tp sequences show <uuid>",
13
13
  "tp sequences summary <uuid>",
14
- "tp candidates list --sequence <uuid> [--all] [--limit <n>]",
15
- "tp candidates search --query <text> [--all] [--limit <n>]",
16
- "tp candidates show <id> [--conversations] [--reminders]",
14
+ "tp candidates list --sequence <uuid> [--all]",
15
+ "tp candidates search --query <text> [--all]",
16
+ "tp candidates show <id> [--conversations] [--reminders] [--memory]",
17
17
  "tp candidates add-note <id> --text <note> [--confirm-write --approval-token <token>]",
18
18
  "tp candidates send-email <id> [--recipient <email>] --subject <subject> --body <body> [--idempotency-key <key>] [--confirm-write --approval-token <token>]",
19
19
  "tp candidates send-sms <id> --message <message> [--recipient <phone>] [--sequence <uuid>] [--idempotency-key <key>] [--confirm-write --approval-token <token>]",
20
- "tp candidates engaged --sequence <uuid> [--all] [--limit <n>]",
20
+ "tp candidates engaged --sequence <uuid> [--all]",
21
21
  "tp candidates provenance <id> [--field <name>] [--days <n>] [--limit <n>]",
22
22
  "tp candidates timeline <id> [--kinds <list>] [--days <n>] [--limit <n>]",
23
23
  "tp candidates records <id> [--record-type <type>] [--days <n>] [--limit <n>]",
24
24
  "tp leads maturity <id>",
25
25
  "tp leads consent-evidence [--candidate <id>] [--limit <n>]",
26
- "tp reminders list [--owner <id>] [--due <when>] [--status <status>] [--all] [--limit <n>]",
26
+ "tp reminders list [--owner <id>] [--due <when>] [--status <status>] [--all]",
27
27
  "tp reminders create [--candidate <id>] --due <when> --text <text> [--confirm-write --approval-token <token>]",
28
28
  "tp reminders complete <id> [--confirm-write --approval-token <token>]",
29
29
  "tp capabilities list",
@@ -37,7 +37,7 @@ COMMANDS = [
37
37
  "tp campaigns deliverability <uuid>",
38
38
  "tp copilot brief [--recruiter <id>] [--since <when>]",
39
39
  "tp copilot ask <prompt>",
40
- "tp interviews list --sequence <uuid> [--all] [--limit <n>]",
40
+ "tp interviews list --sequence <uuid> [--all]",
41
41
  "tp interviews show <uuid>",
42
42
  "tp interviews create-link --candidate <id> --sequence <uuid> [--base-url <url>] [--confirm-write --approval-token <token>]",
43
43
  "tp recruiters notify --candidate <id> --sequence <uuid> --update <text> [--update <text> ...] [--action-needed <text>] [--action-tag <tag>] [--subject <text>] [--message <text>] [--force-channel <channel> ...] [--confirm-write --approval-token <token>]",
@@ -45,10 +45,15 @@ COMMANDS = [
45
45
  "tp metrics --sequence <uuid>",
46
46
  "tp activity summary [--days <n>] [--sequence <uuid>]",
47
47
  "tp chats summary [--days <n>] [--sequence <uuid>] [--candidate <id>] [--limit <n>]",
48
- "tp chats messages [--chat-id <id>] [--days <n>] [--sequence <uuid>] [--candidate <id>] [--limit <n>]",
48
+ "tp chats messages [--chat-id <id> | --chat-ids <ids>] [--candidate <id> | --candidates <ids>] [--sequence <uuid>] [--campaign <uuid>] [--search <text>] [--role human,ai,system,worker,wait|all] [--days <n> | --since <date> --until <date>] [--limit <n>] [--offset <n>]",
49
49
  "tp chats diagnose --chat-id <id>",
50
- "tp ops delivery-status [--candidate <id>] [--sequence <uuid>] [--channel sms|email|phone] [--days <n>] [--limit <n>]",
50
+ "tp chats reply-invariant [--days <n>]",
51
+ "tp chats findings [--since <days>] [--check <name>] [--chat-id <id>] [--severity P0|P1|P2] [--include-resolved]",
52
+ "tp ops delivery-status [--candidate <id> | --candidates <ids>] [--sequence <uuid>] [--campaign <uuid>] [--source <tag>] [--channel sms|email|phone] [--days <n> | --since <date> --until <date>] [--limit <n>]",
51
53
  "tp ops decision-logs [--loop nudge|keepwarm] [--days <n>] [--candidate <id>] [--chat-id <id>] [--outcome <outcome>] [--skip-reason <reason>] [--limit <n>]",
54
+ "tp applications list [--candidate <id> | --candidates <ids>] [--job <ids>] [--campaign <uuid>] [--sequence <uuid>] [--channel <source_channel>] [--status <status>] [--days <n> | --since <date> --until <date>] [--limit <n>] [--offset <n>]",
55
+ "tp agent-runs list [--chat-id <id> | --chat-ids <ids>] [--candidate <id> | --candidates <ids>] [--agent <name>] [--status pending|running|succeeded|failed] [--errors-only] [--entries] [--include-simulator] [--days <n> | --since <date> --until <date>] [--limit <n>] [--offset <n>]",
56
+ "tp job-alerts list [--candidate <id> | --candidates <ids>] [--active-only] [--role <text>] [--location <text>] [--days <n> | --since <date> --until <date>] [--limit <n>] [--offset <n>]",
52
57
  "tp recruiter-actions list [--days <n>] [--unresolved] [--status <status>] [--assignment-status <status>] [--action-type <type>] [--priority <p>] [--candidate <id>] [--limit <n>]",
53
58
  "tp recruiter-actions show <action-id>",
54
59
  "tp recruiter-actions complete <action-id> [--note <text>] [--confirm-write --approval-token <token>]",
@@ -86,7 +91,7 @@ A person signs in with `tp login`: it opens the browser, you pick a team and app
86
91
 
87
92
  For automation, CI and agents, use an API key: `TALENTPRISM_API_KEY` (preferred), `--api-key`, or the profile `api_key`. Precedence is `--api-key` flag, then `TALENTPRISM_API_KEY`, then login tokens, then the profile `api_key`. The default server is `https://talentprism.ai`; set `TALENTPRISM_BASE_URL` (or `--base-url`) for staging or local fleetapp. Avoid passing `--api-key` on the command line: it leaks into shell history and process listings. Non-local base URLs must use https; plain http is rejected unless `TALENTPRISM_ALLOW_INSECURE_HTTP=1` is set.
88
93
 
89
- **A key inherits its user's team role, and `ops.*` needs admin.** `tp ops delivery-status` and `tp ops decision-logs` are admin-only. A key issued from an account that is a plain *member* of the team authenticates perfectly and then fails every `ops` call with `not_authorized` (exit 3). Check with `tp whoami` before relying on a key for production diagnostics; if it is not an admin key, grant that user admin on the team or reissue the key from an admin account. Everything else in this document - including `tp chats diagnose` and all four `tp recruiter-actions` commands - works at member level.
94
+ **A key inherits its user's team role, and `ops.*` needs admin.** `tp ops delivery-status`, `tp ops decision-logs` and `tp agent-runs list` are admin-only. A key issued from an account that is a plain *member* of the team authenticates perfectly and then fails every `ops` call with `not_authorized` (exit 3). Check with `tp whoami` before relying on a key for production diagnostics; if it is not an admin key, grant that user admin on the team or reissue the key from an admin account. Everything else in this document - including `tp chats diagnose` and all four `tp recruiter-actions` commands - works at member level.
90
95
 
91
96
  A `not_authorized` error is never a reason to rotate the key. It means the key worked and its user lacks the role.
92
97
 
@@ -96,7 +101,7 @@ A `not_authorized` error is never a reason to rotate the key. It means the key w
96
101
 
97
102
  ## Output And Errors
98
103
 
99
- Use `--output json` when an agent needs structured data. Use `tp capabilities list --json` to discover typed Agent Capability schemas and policies generated by the Django registry; use `tp capabilities mcp --json` for MCP-style tool metadata; use `tp capabilities commands --json` to generate `tp capabilities invoke ...` examples from the live registry; use `tp capabilities invoke <name> --input-json <json>` for registry-driven execution. A write command without approval flags is a non-mutating proposal and returns its resolved preview plus a 15-minute, one-shot approval token. Execute only by repeating the exact command and arguments with `--confirm-write --approval-token <token>`. List commands (`sequences list`, `candidates list|search|engaged`, `reminders list`, `interviews list`) stop with `too_many_results` when a list has more than 100 items. Pass `--limit N` for the first N rows in the server's order (the payload reports `count`, the server's total, and `truncated`), or `--all` to fetch every page; the two cannot be combined. Successful command data is written to stdout. Errors are JSON on stderr with `code`, `type`, `message`, `details`, and `remediation`.
104
+ Use `--output json` when an agent needs structured data. Use `tp capabilities list --json` to discover typed Agent Capability schemas and policies generated by the Django registry; use `tp capabilities mcp --json` for MCP-style tool metadata; use `tp capabilities commands --json` to generate `tp capabilities invoke ...` examples from the live registry; use `tp capabilities invoke <name> --input-json <json>` for registry-driven execution. A write command without approval flags is a non-mutating proposal and returns its resolved preview plus a 15-minute, one-shot approval token. Execute only by repeating the exact command and arguments with `--confirm-write --approval-token <token>`. Successful command data is written to stdout. Errors are JSON on stderr with `code`, `type`, `message`, `details`, and `remediation`.
100
105
 
101
106
  Chat and message counts never include simulator or eval-fork conversations - they carry a real team and a real candidate but were typed by a tester, so counting them as engagement has repeatedly misled production audits. `tp activity summary` reports what it left out under `excluded` (`chats`, `chat_messages`), so "12 conversations" is never silently "9 real plus 3 test runs".
102
107
 
@@ -123,10 +128,23 @@ Exit codes: 0 success, 2 invalid input, 3 auth, 4 not found, 5 validation, 6 tra
123
128
  - `tp ops delivery-status` - was it actually sent? Reports every record on both SMS send paths with its own proof field, and classifies each as `sent`, `failed`, `in_flight`, `sent_without_sid` (marked sent but carrying no SID - never proof), or `skipped`. An empty result on one path is not evidence that nothing was sent.
124
129
  - `tp ops decision-logs` - what did the nudge and keep-warm loops decide, and what does each outcome mean. Separates dry-run sends from real ones. For keep-warm, a row saying `sent_pitch` proves nothing on its own: only a non-empty `message_sid` on the linked touchpoint does, and the payload reports that per row.
125
130
  - `tp recruiter-actions list --unresolved` - which handoffs and alerts nobody has acted on. Delivery status (`sent`, `held_for_digest`, `digest_sent`, `failed`) and human resolution (`team_queue`, `accepted`, `completed`, `escalated`) are separate fields: a delivered alert can still be untouched.
131
+ - `tp chats reply-invariant [--days <n>]` - reply-invariant ledger counts for the team: every candidate message by outcome (answered, recovered, relayed late, no reply needed, superseded, apologised, escalated, unanswered), answer latency p50/p95, and the chats escalated to a recruiter.
126
132
  - `tp chats diagnose --chat-id <id>` - conversation QA for one chat: duplicate assistant messages, candidate turns with no reply, repeated system recovery, and cross-campaign routing. Each check returns `clear`, `finding` (with message ids and timestamps), or `inconclusive` with the reason. It never guesses.
133
+ - `tp chats findings --since <days>` - the same checks, already run overnight (06:00 UTC) on every chat active in the last 72 hours and stored per finding with first_seen, last_seen and resolved_at. Use this for a team-wide view; use `diagnose` for one chat right now.
127
134
 
128
135
  `ops.*` reads require the admin role - see Auth above. Everything else here works for a plain member.
129
136
 
137
+ ## Across Records
138
+
139
+ Questions that span many chats, sends or applications. Each is one team-scoped read; filters combine. Dates are `--since`/`--until` (ISO dates; `--until 2026-09-30` covers that whole day) or `--days`. Id lists are comma separated. When `truncated` is true, pass `next_offset` back as `--offset`. A "campaign" is the bounded round (`--campaign <uuid>`), not the job sequence (`--sequence`); messages and sends record only the sequence, so for those two `--campaign` reads its execution sequence and the scope lists every campaign sharing it.
140
+
141
+ - `tp chats messages --candidates 101,102 --role human --since 2026-11-01` - what these people said, across all their chats. `--search TWIC` matches message text; `--role all` adds system, worker and wait rows (admin keys only). A read scoped to chats or candidates covers their whole history unless you pass a date; a team-wide read defaults to the last 7 days. Every response states the window it used under `range`.
142
+ - `tp ops delivery-status --campaign <uuid> --since 2026-09-01 --until 2026-09-30` - every send for a round, on both send paths, with SID and result. `--source keepwarm` (or a batch tag) narrows to one sender; `--candidates` to people. Admin only.
143
+ - `tp applications list --job 217565` - applications to a job, a round (`--campaign`), a person, or a window, with status, channel, the round each is credited to and the recruiter it went to. `source_channel` (how it arrived) and `source_campaign_id` (which round) are separate facts; neither implies the job.
144
+ - `tp agent-runs list --chat-id <id> --entries` - what the TinyLLM workers did: agent, tools used, status, error, duration, and whether the result reached the candidate. A `succeeded` run with no `delivered_at` finished but was never relayed. `--errors-only` for failures. Admin only.
145
+ - `tp job-alerts list --active-only` - alert subscriptions with totals as rows and as people (one person can hold several).
146
+ - `tp candidates show <id> --memory` - the current CandidateMemory facts. Who wrote each fact is `tp candidates provenance <id>`.
147
+
130
148
  ## Evidence Reads
131
149
 
132
150
  These answer "show me the record, not the conclusion". All are member-level reads.
@@ -3,7 +3,7 @@ from __future__ import annotations
3
3
  import time
4
4
  from email.utils import parsedate_to_datetime
5
5
  from typing import Any, Callable
6
- from urllib.parse import parse_qsl, urlencode, urlparse, urlsplit, urlunsplit
6
+ from urllib.parse import urlparse
7
7
 
8
8
  from . import __version__
9
9
  from .config import TalentPrismConfig
@@ -15,7 +15,6 @@ RequestFn = Callable[..., Any]
15
15
 
16
16
  RETRY_BACKOFF_SECONDS = 0.2
17
17
  MAX_PAGES = 1000
18
- MAX_PAGE_SIZE = 100 # the server's page_size ceiling
19
18
  ERROR_BODY_PREVIEW_CHARS = 2000
20
19
  MAX_RETRY_AFTER_SECONDS = 10.0
21
20
 
@@ -33,28 +32,24 @@ class APIClient:
33
32
  def get(self, path: str) -> Any:
34
33
  return self._send("GET", path)
35
34
 
36
- def get_paginated(self, path: str, *, all_pages: bool = False, cap: int = 100, limit: int | None = None) -> Any:
37
- # A limit is the caller refining the request, so it replaces the cap check: fetch only as many
38
- # pages as needed for the first `limit` rows, in the server's order.
39
- if limit is not None:
40
- path = _with_page_size(path, min(limit, MAX_PAGE_SIZE))
35
+ def get_paginated(self, path: str, *, all_pages: bool = False, cap: int = 100) -> Any:
41
36
  first_page = self.get(path)
42
37
  if not _is_paginated(first_page):
43
38
  return first_page
44
39
  total_count = first_page.get("count", 0)
45
- if limit is None and total_count > cap and not all_pages:
40
+ if total_count > cap and not all_pages:
46
41
  raise TalentPrismError(
47
42
  code="too_many_results",
48
43
  type="validation",
49
44
  message="List result exceeds the safe automatic cap.",
50
45
  details={"count": total_count, "cap": cap},
51
- remediation="Refine the query, pass --limit N for the first N rows, or pass --all to walk every page.",
46
+ remediation="Refine the query or pass --all to walk every page.",
52
47
  )
53
48
 
54
49
  results = list(first_page.get("results", []))
55
50
  next_url = first_page.get("next")
56
51
  seen_urls: set[str] = set()
57
- while next_url and (limit is None or len(results) < limit):
52
+ while next_url:
58
53
  if next_url in seen_urls or len(seen_urls) >= MAX_PAGES:
59
54
  raise TalentPrismError(
60
55
  code="pagination_not_terminating",
@@ -67,14 +62,6 @@ class APIClient:
67
62
  page = self.get(next_url)
68
63
  results.extend(page.get("results", []))
69
64
  next_url = page.get("next")
70
- if limit is not None:
71
- return {
72
- **first_page,
73
- "next": None,
74
- "results": results[:limit],
75
- "truncated": total_count > limit,
76
- "limit": limit,
77
- }
78
65
  return {**first_page, "next": None, "results": results, "truncated": False}
79
66
 
80
67
  def post(self, path: str, payload: dict[str, Any]) -> Any:
@@ -288,11 +275,3 @@ def _safe_json(response) -> Any:
288
275
 
289
276
  def _is_paginated(payload: Any) -> bool:
290
277
  return isinstance(payload, dict) and "results" in payload and "count" in payload
291
-
292
-
293
- def _with_page_size(path: str, page_size: int) -> str:
294
- """Set page_size on a path, keeping any query string it already carries."""
295
- parts = urlsplit(path)
296
- query = [(key, value) for key, value in parse_qsl(parts.query, keep_blank_values=True) if key != "page_size"]
297
- query.append(("page_size", str(page_size)))
298
- return urlunsplit(parts._replace(query=urlencode(query)))
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: talentprism-cli
3
- Version: 0.3.1
3
+ Version: 0.4.0
4
4
  Summary: Command line for TalentPrism: team-scoped recruiting data and actions for people and AI agents
5
5
  License-Expression: LicenseRef-Proprietary
6
6
  Project-URL: Homepage, https://talentprism.ai
@@ -65,13 +65,13 @@ When several credentials are present, `tp` uses the first of: the `--api-key` fl
65
65
  tp whoami
66
66
  tp sequences list --status Active --json
67
67
  tp candidates search --query "aircraft assembler North Charleston" --json
68
- tp candidates search --query "welder" --limit 20 --json
69
68
  tp activity summary --days 14 --json
70
69
  tp candidates timeline <candidate_id> --days 30 --json
70
+ tp chats messages --candidates 101,102 --role human --since 2026-11-01 --json
71
+ tp applications list --job 217565 --json
72
+ tp agent-runs list --chat-id 4204 --entries --json
71
73
  ```
72
74
 
73
- List commands stop with `too_many_results` when a list has more than 100 items. Add `--limit N` for the first N rows in the server's order (the result keeps `count`, the server's total, and sets `truncated`), or `--all` to fetch every page. The two cannot be combined.
74
-
75
75
  ## Changing data
76
76
 
77
77
  Every write is two steps. Run the command once to get a preview and a one-time approval token. Nothing changes. Then run the same command again with `--confirm-write --approval-token <token>`:
@@ -15,6 +15,7 @@ talentprism_cli/loopback.py
15
15
  talentprism_cli/network_bootstrap.py
16
16
  talentprism_cli/oauth.py
17
17
  talentprism_cli/readonly_api.py
18
+ talentprism_cli/record_reads.py
18
19
  talentprism_cli/sequence_writes.py
19
20
  talentprism_cli/skill.py
20
21
  talentprism_cli/transport.py
@@ -1 +0,0 @@
1
- __version__ = "0.3.1"