manage_party

Instructions

Implementation Reference

• src/modules/data.ts:1489-1534 (handler)

  The main handler function for the 'manage_party' tool. Parses input using managePartySchema, dispatches to specific operation handlers (add, remove, list, get, set_role, clear), formats output as ASCII box, and handles Zod validation errors.

  export async function manageParty(input: unknown): Promise<{ content: { type: 'text'; text: string }[] }> {
    try {
      const parsed = managePartySchema.parse(input);
  
      let result: string;
  
      switch (parsed.operation) {
        case 'add':
          result = handlePartyAdd(parsed);
          break;
        case 'remove':
          result = handlePartyRemove(parsed);
          break;
        case 'list':
          result = handlePartyList();
          break;
        case 'get':
          result = handlePartyGet(parsed);
          break;
        case 'set_role':
          result = handlePartySetRole(parsed);
          break;
        case 'clear':
          result = handlePartyClear();
          break;
        default:
          result = createBox('ERROR', ['Unknown operation'], DISPLAY_WIDTH);
      }
  
      return { content: [{ type: 'text' as const, text: result }] };
    } catch (error) {
      const lines: string[] = [];
  
      if (error instanceof z.ZodError) {
        for (const issue of error.issues) {
          lines.push(`${issue.path.join('.')}: ${issue.message}`);
        }
      } else if (error instanceof Error) {
        lines.push(error.message);
      } else {
        lines.push('An unknown error occurred');
      }
  
      return { content: [{ type: 'text' as const, text: createBox('ERROR', lines, DISPLAY_WIDTH) }] };
    }
  }

• src/modules/data.ts:1163-1170 (schema)

  Zod schema defining input validation for manage_party tool using discriminated union on 'operation' field for add/remove/list/get/set_role/clear operations.

  export const managePartySchema = z.discriminatedUnion('operation', [
    addPartyOperationSchema,
    removePartyOperationSchema,
    listPartyOperationSchema,
    getPartyMemberOperationSchema,
    setRoleOperationSchema,
    clearPartyOperationSchema,
  ]);

• src/registry.ts:1097-1114 (registration)

  Tool registration in the central registry, defining name, description, input schema conversion, and wrapper handler that calls the manageParty function with error handling.

  manage_party: {
    name: 'manage_party',
    description: 'Manage party composition. Operations: add (add character to party with optional role), remove (remove character from party), list (show party roster), get (get party member details), set_role (assign role to party member), clear (remove all members). Roles: leader, scout, healer, tank, support, damage, utility, other.',
    inputSchema: toJsonSchema(managePartySchema),
    handler: async (args) => {
      try {
        const result = await manageParty(args);
        return result;
      } catch (err) {
        if (err instanceof z.ZodError) {
          const messages = err.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ');
          return error(`Validation failed: ${messages}`);
        }
        const message = err instanceof Error ? err.message : String(err);
        return error(message);
      }
    },
  },

• src/modules/data.ts:1226-1265 (helper)

  Example helper: handlePartyAdd - Resolves character ID, checks if already in party, adds to partyMemberStore with role, formats output.

  function handlePartyAdd(input: z.infer<typeof addPartyOperationSchema>): string {
    const resolved = resolveCharacterId(input.characterId, input.characterName);
  
    if (!resolved.id) {
      return createBox('ERROR', [resolved.error || 'Character not found'], DISPLAY_WIDTH);
    }
  
    // Check if already in party
    if (partyMemberStore.has(resolved.id)) {
      const charResult = getCharacter({ characterId: resolved.id });
      const name = charResult.character?.name || resolved.id;
      return createBox('ERROR', [`${name} is already in the party.`], DISPLAY_WIDTH);
    }
  
    // Get character info for display
    const charResult = getCharacter({ characterId: resolved.id });
    const character = charResult.character;
  
    // Add to party
    const member: PartyMember = {
      characterId: resolved.id,
      characterName: character?.name || resolved.id,
      role: input.role,
      joinedAt: new Date().toISOString(),
    };
    partyMemberStore.set(resolved.id, member);
  
    const lines: string[] = [];
    lines.push(`Name: ${character?.name || resolved.id}`);
    if (character) {
      lines.push(`Class: ${character.class} (Level ${character.level})`);
    }
    if (input.role) {
      lines.push(`Role: ${input.role}`);
    }
    lines.push('');
    lines.push(`Party size: ${partyMemberStore.size}`);
  
    return createBox('PARTY MEMBER ADDED', lines, DISPLAY_WIDTH);
  }