@aopslabs/aops 0.3.7 → 0.3.8

package/dist/commands/discuss.js

@@ -229,19 +229,41 @@ async function invokeDiscussionTool(options, context, params) {
         idempotencyKey: options.idempotencyKey,
     });
 }
+export function resolveMutationOutcome(options) {
+    const mutationRequested = options.apply === true && options.preview !== true;
+    const hasIdempotencyKey = Boolean(normalizeNonEmpty(options.idempotencyKey));
+    return {
+        mutationRequested,
+        mutationApplied: mutationRequested === false ? false : hasIdempotencyKey ? null : true,
+        mutationOutcome: mutationRequested === false ? 'preview' : hasIdempotencyKey ? 'applied-or-replayed' : 'applied',
+    };
+}
 function emitEnvelope(params) {
-    const envelope = buildHostedSugarEnvelope({
-        command: params.command,
-        toolId: params.toolId,
-        resolvedContext: buildResolvedContextRecord(params.resolvedContext),
-        input: params.input,
-        result: params.result,
+    const mutation = params.mutation === true ? resolveMutationOutcome(params.options) : undefined;
+    const envelope = compactPayload({
+        ...buildHostedSugarEnvelope({
+            command: params.command,
+            toolId: params.toolId,
+            resolvedContext: buildResolvedContextRecord(params.resolvedContext),
+            input: params.input,
+            result: params.result,
+        }),
+        mutationRequested: mutation?.mutationRequested,
+        mutationApplied: mutation?.mutationApplied,
+        mutationOutcome: mutation?.mutationOutcome,
     });
     if (params.options.json) {
         console.log(JSON.stringify(envelope, null, 2));
         return;
     }
-    logSuccess(params.successMessage);
+    const successMessage = params.mutation !== true
+        ? params.successMessage
+        : mutation?.mutationOutcome === 'preview'
+            ? 'Preview completed; hosted state was not mutated.'
+            : mutation?.mutationOutcome === 'applied-or-replayed'
+                ? 'Apply request completed; idempotency may have replayed the original result, so no second write is claimed.'
+                : params.successMessage;
+    logSuccess(successMessage);
     console.log(JSON.stringify(params.result, null, 2));
 }
 async function readTextInput(params, label) {
@@ -273,6 +295,25 @@ function requireTopicSelector(value, flag) {
         throw new Error(`Provide ${flag} <topic-id|slug>.`);
     return selector;
 }
+export function resolveTopicSelectorAliases(topic, id) {
+    const canonical = normalizeNonEmpty(topic);
+    const legacy = normalizeNonEmpty(id);
+    if (canonical && legacy && canonical !== legacy) {
+        throw new Error(`--topic and legacy --id conflict. Pass one selector, or provide the same value to both.`);
+    }
+    return requireTopicSelector(canonical ?? legacy, '--topic');
+}
+export function resolveAgentSelectorAliases(agent, legacyFor) {
+    const canonical = normalizeNonEmpty(agent);
+    const legacy = normalizeNonEmpty(legacyFor);
+    if (canonical && legacy && canonical !== legacy) {
+        throw new Error(`--agent and legacy --for conflict. Pass one agent selector, or provide the same value to both.`);
+    }
+    const selector = canonical ?? legacy;
+    if (!selector)
+        throw new Error('Provide --agent <agent-id>.');
+    return selector;
+}
 async function resolveTopicId(options, context, selector) {
     const scopeId = requireScopeId(context);
     if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(selector)) {
@@ -493,6 +534,7 @@ export async function runDiscussStart(options = {}) {
             input: { data },
             result,
             successMessage: 'Hosted discussion topic started.',
+            mutation: true,
         });
     }
     catch (error) {
@@ -572,6 +614,7 @@ async function runDiscussChildTopic(options, params) {
             input: { data },
             result,
             successMessage: params.successMessage,
+            mutation: true,
         });
     }
     catch (error) {
@@ -647,7 +690,7 @@ export async function runDiscussList(options = {}) {
 export async function runDiscussGet(options = {}) {
     try {
         const context = await resolveDiscussionContext(options);
-        const selector = requireTopicSelector(options.id, '--id');
+        const selector = resolveTopicSelectorAliases(options.topic, options.id);
         const topicId = await resolveTopicId(options, context, selector);
         const detail = await fetchTopicDetail(options, context, topicId);
         const result = compactPayload({
@@ -752,7 +795,7 @@ function parseSeq(value, flag) {
 export async function runDiscussTurn(options = {}) {
     try {
         ensureGuardedWrite(options, 'This command appends a turn to a hosted discussion topic.');
-        const selector = requireTopicSelector(options.topic, '--topic');
+        const selector = resolveTopicSelectorAliases(options.topic, options.id);
         const agentId = normalizeNonEmpty(options.agent);
         if (!agentId)
             throw new Error('Provide --agent.');
@@ -804,6 +847,7 @@ export async function runDiscussTurn(options = {}) {
             input: { data },
             result,
             successMessage: 'Hosted discussion turn written.',
+            mutation: true,
         });
     }
     catch (error) {
@@ -814,7 +858,7 @@ export async function runDiscussTurn(options = {}) {
 export async function runDiscussStatus(options = {}) {
     try {
         const context = await resolveDiscussionContext(options);
-        const selector = requireTopicSelector(options.id, '--id');
+        const selector = resolveTopicSelectorAliases(options.topic, options.id);
         const topicId = await resolveTopicId(options, context, selector);
         const detail = await fetchTopicDetail(options, context, topicId);
         const status = await fetchStatus(options, context, topicId);
@@ -841,7 +885,7 @@ export async function runDiscussStatus(options = {}) {
 export async function runDiscussDigest(options = {}) {
     try {
         const context = await resolveDiscussionContext(options);
-        const selector = requireTopicSelector(options.id, '--id');
+        const selector = resolveTopicSelectorAliases(options.topic, options.id);
         const topicId = await resolveTopicId(options, context, selector);
         const detail = await fetchTopicDetail(options, context, topicId);
         const status = await fetchStatus(options, context, topicId);
@@ -904,9 +948,7 @@ function classifyWaitState(presentation, status, agentId) {
 }
 export async function runDiscussWait(options = {}) {
     try {
-        const agentId = normalizeNonEmpty(options.for);
-        if (!agentId)
-            throw new Error('Provide --for <agent-id>.');
+        const agentId = resolveAgentSelectorAliases(options.agent, options.for);
         const timeoutSec = typeof options.timeoutSec === 'number' && Number.isFinite(options.timeoutSec)
             ? Math.max(0, options.timeoutSec)
             : 300;
@@ -914,7 +956,7 @@ export async function runDiscussWait(options = {}) {
             ? options.intervalSec
             : 5;
         const context = await resolveDiscussionContext(options);
-        const selector = requireTopicSelector(options.id, '--id');
+        const selector = resolveTopicSelectorAliases(options.topic, options.id);
         const topicId = await resolveTopicId(options, context, selector);
         const deadline = Date.now() + timeoutSec * 1000;
         while (true) {
@@ -971,8 +1013,8 @@ export async function runDiscussWait(options = {}) {
     }
 }
 function buildPersistentLoopPrompt(params) {
-    const waitCommand = `aops-cli discuss wait --id ${params.topicSelector} --for ${params.agentId} --timeout-sec ${params.timeoutSec} --interval-sec ${params.intervalSec} --json`;
-    const statusCommand = `aops-cli discuss status --id ${params.topicSelector} --prompt-for-next --json`;
+    const waitCommand = `aops-cli discuss wait --topic ${params.topicSelector} --agent ${params.agentId} --timeout-sec ${params.timeoutSec} --interval-sec ${params.intervalSec} --json`;
+    const statusCommand = `aops-cli discuss status --topic ${params.topicSelector} --prompt-for-next --json`;
     const turnCommand = `aops-cli discuss turn --topic ${params.topicSelector} --agent ${params.agentId} --expect-next ${params.agentId} --kind statement --text "<turn metni>" --apply --json`;
     return [
         `Bu topic'te ${params.agentId} agent olarak kalici loopta calis.`,
@@ -1005,9 +1047,7 @@ function buildPersistentLoopPrompt(params) {
 }
 export async function runDiscussLoopPrompt(options = {}) {
     try {
-        const agentId = normalizeNonEmpty(options.for);
-        if (!agentId)
-            throw new Error('Provide --for <agent-id>.');
+        const agentId = resolveAgentSelectorAliases(options.agent, options.for);
         const timeoutSec = typeof options.timeoutSec === 'number' && Number.isFinite(options.timeoutSec)
             ? Math.max(0, options.timeoutSec)
             : 540;
@@ -1015,7 +1055,7 @@ export async function runDiscussLoopPrompt(options = {}) {
             ? options.intervalSec
             : 5;
         const context = await resolveDiscussionContext(options);
-        const selector = requireTopicSelector(options.id, '--id');
+        const selector = resolveTopicSelectorAliases(options.topic, options.id);
         const topicId = await resolveTopicId(options, context, selector);
         const detail = await fetchTopicDetail(options, context, topicId);
         if (!topicParticipants(detail.topic).some((participant) => participant.toLowerCase() === agentId.toLowerCase())) {
@@ -1028,8 +1068,8 @@ export async function runDiscussLoopPrompt(options = {}) {
             agentId,
             timeoutSec,
             intervalSec,
-            waitCommand: `aops-cli discuss wait --id ${topicSelector} --for ${agentId} --timeout-sec ${timeoutSec} --interval-sec ${intervalSec} --json`,
-            statusCommand: `aops-cli discuss status --id ${topicSelector} --prompt-for-next --json`,
+            waitCommand: `aops-cli discuss wait --topic ${topicSelector} --agent ${agentId} --timeout-sec ${timeoutSec} --interval-sec ${intervalSec} --json`,
+            statusCommand: `aops-cli discuss status --topic ${topicSelector} --prompt-for-next --json`,
             turnCommandTemplate: `aops-cli discuss turn --topic ${topicSelector} --agent ${agentId} --expect-next ${agentId} --kind <statement|final-stance> --text "<turn metni>" --apply --json`,
             prompt,
         });
@@ -1054,7 +1094,7 @@ export async function runDiscussConclude(options = {}) {
     try {
         ensureGuardedWrite(options, 'This command concludes a hosted discussion topic.');
         const context = await resolveDiscussionContext(options);
-        const selector = requireTopicSelector(options.topic, '--topic');
+        const selector = resolveTopicSelectorAliases(options.topic, options.id);
         const topicId = await resolveTopicId(options, context, selector);
         const input = compactPayload({ topicId, updatedBy: normalizeNonEmpty(options.updatedBy) });
         const payload = await invokeDiscussionTool(options, context, {
@@ -1072,6 +1112,7 @@ export async function runDiscussConclude(options = {}) {
             input,
             result,
             successMessage: 'Hosted discussion topic concluded.',
+            mutation: true,
         });
     }
     catch (error) {
@@ -1086,7 +1127,7 @@ export async function runDiscussAbandon(options = {}) {
         if (!reason)
             throw new Error('Provide --reason <text>.');
         const context = await resolveDiscussionContext(options);
-        const selector = requireTopicSelector(options.topic, '--topic');
+        const selector = resolveTopicSelectorAliases(options.topic, options.id);
         const topicId = await resolveTopicId(options, context, selector);
         const input = compactPayload({ topicId, reason });
         const payload = await invokeDiscussionTool(options, context, {
@@ -1104,6 +1145,7 @@ export async function runDiscussAbandon(options = {}) {
             input,
             result,
             successMessage: 'Hosted discussion topic abandoned.',
+            mutation: true,
         });
     }
     catch (error) {
@@ -1116,7 +1158,7 @@ export async function runDiscussOutput(options = {}) {
         ensureGuardedWrite(options, 'This command sets a hosted discussion output.');
         const context = await resolveDiscussionContext(options);
         const scopeId = requireScopeId(context);
-        const selector = requireTopicSelector(options.topic, '--topic');
+        const selector = resolveTopicSelectorAliases(options.topic, options.id);
         const topicId = await resolveTopicId(options, context, selector);
         const outputKind = normalizeNonEmpty(options.outputKind);
         if (!outputKind)
@@ -1141,6 +1183,7 @@ export async function runDiscussOutput(options = {}) {
             input: { data },
             result,
             successMessage: 'Hosted discussion output set.',
+            mutation: true,
         });
     }
     catch (error) {
@@ -1301,16 +1344,18 @@ Notes:
 `);
     const get = cmd.command('get')
         .description('Get a hosted discussion topic with its turns and outputs')
-        .option('--id <id>', 'Hosted topic id or slug')
+        .option('--topic <topic>', 'Hosted topic id or slug')
+        .option('--id <topic>', 'Legacy alias for --topic')
         .action((commandOptions) => runDiscussGet({ ...cmd.opts(), ...commandOptions }));
     addDiscussionContextOptions(get);
     get.addHelpText('after', `
 Examples:
-  aops-cli discuss get --id <topic> --json
+  aops-cli discuss get --topic <topic> --json
 `);
     const turn = cmd.command('turn')
         .description('Append one turn to a hosted discussion topic (turn-order enforced server-side)')
         .option('--topic <id>', 'Hosted topic id or slug')
+        .option('--id <id>', 'Legacy alias for --topic')
         .requiredOption('--agent <id>', 'Participant agent id')
         .requiredOption('--kind <kind>', `Turn kind: ${TURN_KINDS.join('|')}`)
         .option('--text <text>', 'Inline turn content')
@@ -1338,6 +1383,7 @@ Notes:
     const output = cmd.command('output')
         .description('Set a hosted discussion output (conclude-flow output authoring)')
         .option('--topic <id>', 'Hosted topic id or slug')
+        .option('--id <id>', 'Legacy alias for --topic')
         .requiredOption('--output-kind <kind>', 'Output kind: consensus|disagreement|open-questions|final-stance|decision|agent-summary')
         .requiredOption('--owner <agent-id>', 'Owner agent id (must be a topic participant; server-enforced)')
         .option('--text <text>', 'Inline output content (must not contain _TBD_)')
@@ -1357,29 +1403,32 @@ Notes:
 `);
     const status = cmd.command('status')
         .description('Read hosted discussion state mapped to lifecycleState/nextTurn/openQuestions')
-        .option('--id <id>', 'Hosted topic id or slug')
+        .option('--topic <topic>', 'Hosted topic id or slug')
+        .option('--id <topic>', 'Legacy alias for --topic')
         .option('--prompt-for-next', 'Include a deterministic prompt template for the suggested next participant')
         .action((commandOptions) => runDiscussStatus({ ...cmd.opts(), ...commandOptions }));
     addDiscussionContextOptions(status);
     status.addHelpText('after', `
 Examples:
-  aops-cli discuss status --id <topic> --json
-  aops-cli discuss status --id <topic> --prompt-for-next --json
+  aops-cli discuss status --topic <topic> --json
+  aops-cli discuss status --topic <topic> --prompt-for-next --json
 
 Notes:
   - lifecycleState/nextTurn/openQuestions hosted status+get'ten turetilir (server truth)
 `);
     const wait = cmd.command('wait')
         .description('Poll hosted status until an agent may write, an operator block appears, or the topic is ready/done')
-        .option('--id <id>', 'Hosted topic id or slug')
-        .requiredOption('--for <agent-id>', 'Agent id waiting for its next allowed turn')
+        .option('--topic <topic>', 'Hosted topic id or slug')
+        .option('--id <topic>', 'Legacy alias for --topic')
+        .option('--agent <agent-id>', 'Agent id waiting for its next allowed turn')
+        .option('--for <agent-id>', 'Legacy alias for --agent')
         .option('--timeout-sec <sec>', 'Maximum seconds to wait', parseNonNegativeNumber, 300)
         .option('--interval-sec <sec>', 'Polling interval seconds', parsePositiveNumber, 5)
         .action((commandOptions) => runDiscussWait({ ...cmd.opts(), ...commandOptions }));
     addDiscussionContextOptions(wait);
     wait.addHelpText('after', `
 Examples:
-  aops-cli discuss wait --id <topic> --for codex --timeout-sec 540 --interval-sec 5 --json
+  aops-cli discuss wait --topic <topic> --agent codex --timeout-sec 540 --interval-sec 5 --json
 
 Exit codes:
   0   requested agent is allowed to write the next turn
@@ -1389,31 +1438,35 @@ Exit codes:
 `);
     const loopPrompt = cmd.command('loop-prompt')
         .description('Print a persistent agent loop prompt for hosted discussion automation')
-        .option('--id <id>', 'Hosted topic id or slug')
-        .requiredOption('--for <agent-id>', 'Agent id that should keep waiting and writing turns')
+        .option('--topic <topic>', 'Hosted topic id or slug')
+        .option('--id <topic>', 'Legacy alias for --topic')
+        .option('--agent <agent-id>', 'Agent id that should keep waiting and writing turns')
+        .option('--for <agent-id>', 'Legacy alias for --agent')
         .option('--timeout-sec <sec>', 'Maximum seconds per wait cycle', parseNonNegativeNumber, 540)
         .option('--interval-sec <sec>', 'Polling interval seconds', parsePositiveNumber, 5)
         .action((commandOptions) => runDiscussLoopPrompt({ ...cmd.opts(), ...commandOptions }));
     addDiscussionContextOptions(loopPrompt);
     loopPrompt.addHelpText('after', `
 Examples:
-  aops-cli discuss loop-prompt --id <topic> --for claude
-  aops-cli discuss loop-prompt --id <topic> --for claude --timeout-sec 540 --interval-sec 5 --json
+  aops-cli discuss loop-prompt --topic <topic> --agent claude
+  aops-cli discuss loop-prompt --topic <topic> --agent claude --timeout-sec 540 --interval-sec 5 --json
 `);
     const digest = cmd.command('digest')
         .description('Build a non-interpretive hosted discussion context pack')
-        .option('--id <id>', 'Hosted topic id or slug')
+        .option('--topic <topic>', 'Hosted topic id or slug')
+        .option('--id <topic>', 'Legacy alias for --topic')
         .option('--prompt-for-next', 'Include a deterministic prompt template for the suggested next participant')
         .action((commandOptions) => runDiscussDigest({ ...cmd.opts(), ...commandOptions }));
     addDiscussionContextOptions(digest);
     digest.addHelpText('after', `
 Examples:
-  aops-cli discuss digest --id <topic> --json
-  aops-cli discuss digest --id <topic> --prompt-for-next --json
+  aops-cli discuss digest --topic <topic> --json
+  aops-cli discuss digest --topic <topic> --prompt-for-next --json
 `);
     const conclude = cmd.command('conclude')
         .description('Conclude a hosted discussion topic (server enforces min-turns + final-stance readiness)')
         .option('--topic <id>', 'Hosted topic id or slug')
+        .option('--id <id>', 'Legacy alias for --topic')
         .option('--updated-by <agent-id>', 'Optional updatedBy actor')
         .option('--preview', 'Validate without mutating hosted state')
         .option('--apply', 'Conclude the topic')
@@ -1431,6 +1484,7 @@ Notes:
     const abandon = cmd.command('abandon')
         .description('Mark a hosted discussion topic as abandoned')
         .option('--topic <id>', 'Hosted topic id or slug')
+        .option('--id <id>', 'Legacy alias for --topic')
         .requiredOption('--reason <text>', 'Reason recorded in topic metadata')
         .option('--preview', 'Validate without mutating hosted state')
         .option('--apply', 'Abandon the topic')