@clickminded/coauthor-cli 0.0.10 → 0.0.11

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/README.md CHANGED
@@ -148,7 +148,7 @@ Images and threads:
148
148
 
149
149
  ```sh
150
150
  coauthor image list <project-id> --json
151
- coauthor image generate <project-id> --prompt "..." --json
151
+ coauthor image generate <project-id> --placeholder-id <placeholder-id> --prompt "..." --json
152
152
  coauthor thread generate <project-id> --json
153
153
  coauthor thread save <project-id> --data '{"posts":[]}' --json
154
154
  ```
@@ -189,6 +189,7 @@ Agents should:
189
189
  - Use `--json` on every command they need to parse.
190
190
  - Use `--wait` when starting long-running research or draft jobs and the user expects completion.
191
191
  - Treat `status: "requires_key"` as a recoverable pause, not a failed workflow. Tell the user to add keys in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
192
+ - Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
192
193
  - Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Wait for `project_state: "research_structured"` before generating a draft; do not rewind for this state.
193
194
  - Use `coauthor credits <project-id> --json` to inspect credit allowance, pending holds, and remaining credits.
194
195
  - Avoid retrying publish/export after uncertain network failures.
@@ -222,6 +223,10 @@ The CLI talks to `/api/agent/v1/*`. Treat this as a public beta API surface:
222
223
 
223
224
  `requires_key` means included credits are exhausted and no usable provider key is configured for the requested capability. The task is paused when possible. Open AI settings in the web app, add the required key, then run `coauthor workflow resume <project-id> --wait --json`.
224
225
 
226
+ `research_running_stale` means a research run is still marked running beyond the expected progress window. Inspect `coauthor research structured <project-id> --json`; if it only contains empty section shells, rewind research or report the stale run instead of repeatedly resuming.
227
+
228
+ Image generation requires an existing image placeholder. Run `coauthor image list <project-id> --json` after draft generation and pass the placeholder id to `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`.
229
+
225
230
  If `npx @clickminded/coauthor-cli help` fails while you are inside the CLI package source directory, run it from another directory or use:
226
231
 
227
232
  ```sh
@@ -9,4 +9,4 @@ export type CommandContext = {
9
9
  token: string;
10
10
  };
11
11
  export declare function runCommand(input: ParsedCommand, context: CommandContext): Promise<CommandResult>;
12
- export declare function helpResult(): CommandResult;
12
+ export declare function helpResult(command?: string[]): CommandResult;
package/dist/commands.js CHANGED
@@ -632,10 +632,11 @@ function openBrowser(url) {
632
632
  child.unref();
633
633
  }
634
634
  async function waitForResearch(client, projectId, initialData) {
635
- const deadline = Date.now() + 20 * 60_000;
635
+ const deadline = Date.now() + waitTimeoutMs(20 * 60_000);
636
+ const pollMs = waitPollMs();
636
637
  let latest = initialData;
637
638
  while (Date.now() < deadline) {
638
- await sleep(3000);
639
+ await sleep(pollMs);
639
640
  latest = await client.request({ path: `projects/${encodeURIComponent(projectId)}/research/status` });
640
641
  const status = extractNestedString(latest, ['run', 'status']);
641
642
  if (status === 'succeeded')
@@ -645,14 +646,18 @@ async function waitForResearch(client, projectId, initialData) {
645
646
  if (status === 'paused_requires_key') {
646
647
  return requiresKeyPauseResult(projectId, 'research', extractNestedString(latest, ['run', 'error_message']) ?? 'Research paused: add the required API key to continue.', latest);
647
648
  }
649
+ const stale = researchRunningStaleResult(projectId, latest, null, initialData);
650
+ if (stale)
651
+ return stale;
648
652
  }
649
- return { ok: true, message: 'Timed out waiting for research; check status with coauthor research status', data: latest };
653
+ return waitTimedOutResult(projectId, 'research', initialData, latest, null);
650
654
  }
651
655
  async function waitForDraft(client, projectId, initialData) {
652
- const deadline = Date.now() + 20 * 60_000;
656
+ const deadline = Date.now() + waitTimeoutMs(20 * 60_000);
657
+ const pollMs = waitPollMs();
653
658
  let latest = initialData;
654
659
  while (Date.now() < deadline) {
655
- await sleep(3000);
660
+ await sleep(pollMs);
656
661
  latest = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
657
662
  const state = getResponseString(latest, 'project_state');
658
663
  const phase = getResponseString(latest, 'phase');
@@ -664,19 +669,17 @@ async function waitForDraft(client, projectId, initialData) {
664
669
  if (phase === 'failed')
665
670
  throw new Error(getResponseString(latest, 'message') ?? 'Draft generation failed');
666
671
  }
667
- return { ok: true, message: 'Timed out waiting for draft; check status with coauthor draft status', data: latest };
672
+ return waitTimedOutResult(projectId, 'draft', initialData, null, latest);
668
673
  }
669
674
  async function waitForWorkflowDraft(client, projectId, initialData) {
670
- const deadline = Date.now() + 40 * 60_000;
675
+ const deadline = Date.now() + waitTimeoutMs(40 * 60_000);
676
+ const pollMs = waitPollMs();
671
677
  let latestDraft = initialData;
672
678
  let latestResearch = null;
673
679
  let draftGenerate = null;
674
680
  let attemptedDraftStart = false;
675
- if (workflowIndicatesBackgroundResearch(initialData)) {
676
- return researchRunningWorkflowResult(projectId, initialData, null, null);
677
- }
678
681
  while (Date.now() < deadline) {
679
- await sleep(3000);
682
+ await sleep(pollMs);
680
683
  latestDraft = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
681
684
  const draftState = getResponseString(latestDraft, 'project_state');
682
685
  const draftPhase = getResponseString(latestDraft, 'phase');
@@ -713,6 +716,9 @@ async function waitForWorkflowDraft(client, projectId, initialData) {
713
716
  draft_status: latestDraft,
714
717
  });
715
718
  }
719
+ const stale = researchRunningStaleResult(projectId, latestResearch, latestDraft, initialData);
720
+ if (stale)
721
+ return stale;
716
722
  if (!attemptedDraftStart
717
723
  && (researchStatus === 'succeeded' || isResearchReadyForDraft(draftState))
718
724
  && draftPhase !== 'queued'
@@ -731,13 +737,73 @@ async function waitForWorkflowDraft(client, projectId, initialData) {
731
737
  }
732
738
  }
733
739
  }
740
+ return waitTimedOutResult(projectId, 'workflow draft target', initialData, latestResearch, latestDraft);
741
+ }
742
+ function waitPollMs() {
743
+ const raw = Number(process.env.COAUTHOR_CLI_WAIT_POLL_MS);
744
+ return Number.isFinite(raw) && raw >= 0 ? raw : 3000;
745
+ }
746
+ function waitTimeoutMs(defaultMs) {
747
+ const raw = Number(process.env.COAUTHOR_CLI_WAIT_TIMEOUT_MS);
748
+ return Number.isFinite(raw) && raw > 0 ? raw : defaultMs;
749
+ }
750
+ function researchStaleMs() {
751
+ const raw = Number(process.env.COAUTHOR_CLI_RESEARCH_STALE_MS);
752
+ return Number.isFinite(raw) && raw > 0 ? raw : 10 * 60_000;
753
+ }
754
+ function researchRunAgeMs(data) {
755
+ const timestamp = extractNestedString(data, ['run', 'updated_at'])
756
+ ?? extractNestedString(data, ['run', 'created_at']);
757
+ if (!timestamp)
758
+ return null;
759
+ const time = Date.parse(timestamp);
760
+ if (!Number.isFinite(time))
761
+ return null;
762
+ return Date.now() - time;
763
+ }
764
+ function isResearchRunningStale(data) {
765
+ if (extractNestedString(data, ['run', 'status']) !== 'running')
766
+ return false;
767
+ if (getResponseString(data, 'project_state') !== 'research_running')
768
+ return false;
769
+ const ageMs = researchRunAgeMs(data);
770
+ return typeof ageMs === 'number' && ageMs >= researchStaleMs();
771
+ }
772
+ function researchRunningStaleResult(projectId, researchStatus, draftStatus, workflow) {
773
+ if (!isResearchRunningStale(researchStatus))
774
+ return null;
734
775
  return {
735
- ok: true,
736
- message: 'Timed out waiting for workflow draft target; check status with coauthor draft status',
776
+ ok: false,
777
+ status: 'research_running_stale',
778
+ exitCode: 2,
779
+ message: 'Research is still marked running and has not reported a terminal state within the expected window.',
780
+ data: {
781
+ workflow,
782
+ research_status: enrichResearchStatus(researchStatus),
783
+ draft_status: draftStatus,
784
+ next_commands: [
785
+ `coauthor research status ${projectId} --json`,
786
+ `coauthor research structured ${projectId} --json`,
787
+ `coauthor workflow rewind ${projectId} --target research --json`,
788
+ ],
789
+ },
790
+ };
791
+ }
792
+ function waitTimedOutResult(projectId, target, workflow, researchStatus, draftStatus) {
793
+ return {
794
+ ok: false,
795
+ status: 'timed_out',
796
+ exitCode: 2,
797
+ message: `Timed out waiting for ${target}; check status before retrying.`,
737
798
  data: {
738
- workflow: initialData,
739
- research_status: latestResearch,
740
- draft_status: latestDraft,
799
+ workflow,
800
+ research_status: researchStatus,
801
+ draft_status: draftStatus,
802
+ next_commands: [
803
+ `coauthor research status ${projectId} --json`,
804
+ `coauthor draft status ${projectId} --json`,
805
+ `coauthor workflow resume ${projectId} --target draft --wait --json`,
806
+ ],
741
807
  },
742
808
  };
743
809
  }
@@ -790,7 +856,23 @@ function enrichResearchStatus(data) {
790
856
  return data;
791
857
  const runStatus = extractNestedString(data, ['run', 'status']);
792
858
  const projectState = getResponseString(data, 'project_state');
793
- if (runStatus !== 'running' || projectState === 'research_running')
859
+ if (runStatus !== 'running')
860
+ return data;
861
+ if (isResearchRunningStale(data)) {
862
+ return {
863
+ ...data,
864
+ diagnostic: {
865
+ code: 'research_running_stale',
866
+ message: 'Research is still marked running and has not reported a terminal state within the expected window. Inspect structured output before deciding whether to rewind.',
867
+ next_commands: [
868
+ 'coauthor research status <project-id> --json',
869
+ 'coauthor research structured <project-id> --json',
870
+ 'coauthor workflow rewind <project-id> --target research --json',
871
+ ],
872
+ },
873
+ };
874
+ }
875
+ if (projectState === 'research_running')
794
876
  return data;
795
877
  if (projectState === 'research_complete') {
796
878
  return {
@@ -819,29 +901,6 @@ function enrichResearchStatus(data) {
819
901
  },
820
902
  };
821
903
  }
822
- function workflowIndicatesBackgroundResearch(data) {
823
- if (!data || typeof data !== 'object' || Array.isArray(data))
824
- return false;
825
- return getResponseString(data, 'project_state') === 'research_running'
826
- || getResponseString(data, 'status') === 'research_running';
827
- }
828
- function researchRunningWorkflowResult(projectId, workflow, researchStatus, draftStatus) {
829
- return {
830
- ok: true,
831
- status: 'research_running',
832
- message: 'Research is running in the background. Draft generation has not started yet.',
833
- data: {
834
- workflow,
835
- research_status: researchStatus,
836
- draft_status: draftStatus,
837
- next_commands: [
838
- `coauthor research status ${projectId} --json`,
839
- `coauthor workflow resume ${projectId} --target draft --wait --json`,
840
- `coauthor workflow rewind ${projectId} --target research --json`,
841
- ],
842
- },
843
- };
844
- }
845
904
  function requiresKeyPauseResult(projectId, target, message, data) {
846
905
  const resumeCommand = `coauthor workflow resume ${projectId} --target ${target} --wait --json`;
847
906
  return {
@@ -909,10 +968,11 @@ function resourceCommandName(resource) {
909
968
  return 'operation';
910
969
  return resource;
911
970
  }
912
- export function helpResult() {
971
+ export function helpResult(command = []) {
972
+ const scoped = commandHelp(command);
913
973
  return {
914
974
  ok: true,
915
- message: [
975
+ message: scoped ?? [
916
976
  'Usage: coauthor <command> [options]',
917
977
  '',
918
978
  'Commands:',
@@ -939,3 +999,44 @@ export function helpResult() {
939
999
  ].join('\n'),
940
1000
  };
941
1001
  }
1002
+ function commandHelp(command) {
1003
+ const key = command.join(' ');
1004
+ const help = {
1005
+ 'project create': [
1006
+ 'Usage: coauthor project create [--title <title>] [--topic <brief>] [--audience <audience>] [--json]',
1007
+ '',
1008
+ 'Creates a project. When --topic or --audience is provided, CoAuthor seeds the saved contract so workflow briefing review can use that context.',
1009
+ ].join('\n'),
1010
+ 'workflow run': [
1011
+ 'Usage: coauthor workflow run <project-id> --target <outline|research|draft> [--wait] [--briefing-mode auto|strict|off] [--json]',
1012
+ '',
1013
+ '--wait blocks until the requested target completes, pauses for a key, fails, reports stale research, or times out.',
1014
+ ].join('\n'),
1015
+ 'workflow resume': [
1016
+ 'Usage: coauthor workflow resume <project-id> [--target <research|draft>] [--wait] [--json]',
1017
+ '',
1018
+ 'Use after an interruption, timeout, or requires_key pause. For draft targets, --wait continues through research and draft generation.',
1019
+ ].join('\n'),
1020
+ 'draft generate': [
1021
+ 'Usage: coauthor draft generate <project-id> [--wait] [--json]',
1022
+ '',
1023
+ 'Requires project_state "research_structured". If research is still running or structuring, inspect the returned status and next commands.',
1024
+ ].join('\n'),
1025
+ 'draft get': [
1026
+ 'Usage: coauthor draft get <project-id> [--format json|markdown|html|text] [--json]',
1027
+ '',
1028
+ 'Retrieves a saved generated draft. Chat responses are available through coauthor chat show.',
1029
+ ].join('\n'),
1030
+ 'draft save': [
1031
+ 'Usage: coauthor draft save <project-id> --data \'<json>\' [--json]',
1032
+ '',
1033
+ 'Saves a draft document payload through the agent API.',
1034
+ ].join('\n'),
1035
+ 'image generate': [
1036
+ 'Usage: coauthor image generate <project-id> --placeholder-id <placeholder-id> [--prompt "..."] [--json]',
1037
+ '',
1038
+ 'Image generation requires an image placeholder from coauthor image list. Draft generation creates placeholders.',
1039
+ ].join('\n'),
1040
+ };
1041
+ return help[key] ?? null;
1042
+ }
package/dist/index.js CHANGED
@@ -11,7 +11,7 @@ export async function main(argv = process.argv.slice(2)) {
11
11
  try {
12
12
  const parsed = parseCliArgs(argv);
13
13
  if (parsed.globals.help) {
14
- process.stdout.write(renderResult(helpResult(), parsed.globals.json));
14
+ process.stdout.write(renderResult(helpResult(parsed.command), parsed.globals.json));
15
15
  return 0;
16
16
  }
17
17
  const runtimeConfig = await resolveRuntimeConfig({
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.10",
3
+ "version": "0.0.11",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -16,8 +16,11 @@ This skill guides agent use of the CoAuthor CLI.
16
16
  - Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` when the user explicitly wants a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
17
17
  - Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
18
18
  - Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
19
+ - Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
19
20
  - Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Keep waiting or resume toward draft; do not rewind or generate a draft until project state reaches `research_structured`.
20
21
  - If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
22
+ - `coauthor workflow run <project-id> --target draft --wait` should not be treated as complete until the CLI reports draft completion, a key pause, terminal failure, `research_running_stale`, or `timed_out`.
23
+ - For images, run `coauthor image list <project-id> --json` and pass an existing placeholder with `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`. Draft generation creates placeholders.
21
24
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
22
25
  - After a timeout, interruption, network error, or unclear result, check operation status before retrying.
23
26
  - `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
@@ -16,8 +16,11 @@ This skill guides agent use of the CoAuthor CLI.
16
16
  - Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` when the user explicitly wants a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
17
17
  - Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
18
18
  - Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
19
+ - Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
19
20
  - Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Keep waiting or resume toward draft; do not rewind or generate a draft until project state reaches `research_structured`.
20
21
  - If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
22
+ - `coauthor workflow run <project-id> --target draft --wait` should not be treated as complete until the CLI reports draft completion, a key pause, terminal failure, `research_running_stale`, or `timed_out`.
23
+ - For images, run `coauthor image list <project-id> --json` and pass an existing placeholder with `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`. Draft generation creates placeholders.
21
24
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
22
25
  - After a timeout, interruption, network error, or unclear result, check operation status before retrying.
23
26
  - `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
@@ -16,8 +16,11 @@ This skill guides agent use of the CoAuthor CLI.
16
16
  - Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` when the user explicitly wants a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
17
17
  - Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
18
18
  - Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
19
+ - Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
19
20
  - Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Keep waiting or resume toward draft; do not rewind or generate a draft until project state reaches `research_structured`.
20
21
  - If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
22
+ - `coauthor workflow run <project-id> --target draft --wait` should not be treated as complete until the CLI reports draft completion, a key pause, terminal failure, `research_running_stale`, or `timed_out`.
23
+ - For images, run `coauthor image list <project-id> --json` and pass an existing placeholder with `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`. Draft generation creates placeholders.
21
24
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
22
25
  - After a timeout, interruption, network error, or unclear result, check operation status before retrying.
23
26
  - `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
@@ -13,8 +13,11 @@ alwaysApply: true
13
13
  - Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` for a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
14
14
  - Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
15
15
  - Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
16
+ - Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
16
17
  - Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Keep waiting or resume toward draft; do not rewind or generate a draft until project state reaches `research_structured`.
17
18
  - If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
19
+ - `coauthor workflow run <project-id> --target draft --wait` should not be treated as complete until the CLI reports draft completion, a key pause, terminal failure, `research_running_stale`, or `timed_out`.
20
+ - For images, run `coauthor image list <project-id> --json` and pass an existing placeholder with `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`. Draft generation creates placeholders.
18
21
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
19
22
  - After timeout, interruption, network error, or ambiguous output, check operation status before retrying or reporting success.
20
23
  - `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.